diff --git a/.gitignore b/.gitignore index b0aac3d91..f0238d4db 100644 --- a/.gitignore +++ b/.gitignore @@ -51,3 +51,6 @@ dashboard/package-lock.json dashboard/src/.umi/ package-lock.json dashboard/src/.umi-production/ + +# Swagger: generate Restful API +pkg/server/docs/index.html diff --git a/Makefile b/Makefile index ebe4d803f..41f6b0d98 100644 --- a/Makefile +++ b/Makefile @@ -64,6 +64,11 @@ doc-gen: go run hack/docgen/gen.go go run hack/references/generate.go +api-gen: + swag init -g pkg/server/route.go --output pkg/server/docs + swagger-codegen generate -l html2 -i pkg/server/docs/swagger.yaml -o pkg/server/docs + mv pkg/server/docs/index.html docs/en/developers/references/restful-api/ + generate-source: go run hack/frontend/source.go diff --git a/dashboard/config/proxy.ts b/dashboard/config/proxy.ts index a4c61c979..0b03cca59 100644 --- a/dashboard/config/proxy.ts +++ b/dashboard/config/proxy.ts @@ -1,7 +1,7 @@ export default { dev: { '/api/': { - target: 'http://localhost:8081/', + target: 'http://localhost:38081/', changeOrigin: true, }, }, diff --git a/docs/en/_sidebar.md b/docs/en/_sidebar.md index 191d23285..2b4f4247e 100644 --- a/docs/en/_sidebar.md +++ b/docs/en/_sidebar.md @@ -42,6 +42,7 @@ - [Rollout](/en/developers/references/traits/rollout.md) - [Metrics](/en/developers/references/traits/metrics.md) - [Scaler](/en/developers/references/traits/scaler.md) + - [Restful APi](/en/developers/references/restful-api/index.html ':ignore') - CLI - General - [vela config](/en/cli/vela_config.md) @@ -75,5 +76,4 @@ - [vela template](/en/cli/vela_template.md) - Extensibility - [vela cap](/en/cli/vela_cap.md) - - [Restful APi](/en/developers/references/restful-api/index.html ':ignore') - [FAQ](/en/developers/references/devex/faq.md) diff --git a/pkg/server/appHandlers.go b/pkg/server/appHandlers.go index 93fee7ada..39f4c49ae 100644 --- a/pkg/server/appHandlers.go +++ b/pkg/server/appHandlers.go @@ -12,7 +12,7 @@ import ( func (s *APIServer) UpdateApps(c *gin.Context) { } -// GetApp requests an application by the namespacedname in the gin.Context +// GetApp requests an application by the namespaced name in the gin.Context func (s *APIServer) GetApp(c *gin.Context) { envName := c.Param("envName") envMeta, err := env.GetEnvByName(envName) @@ -32,6 +32,13 @@ func (s *APIServer) GetApp(c *gin.Context) { } // ListApps requests a list of application by the namespace in the gin.Context +// @tags applications +// @ID ListApplications +// @Summary list all applications +// @Param envName path string true "environment name" +// @Success 200 {object} apis.Response{code=int,data=[]apis.ApplicationMeta} +// @Failure 500 {object} apis.Response{code=int,data=string} +// @Router /envs/{envName}/apps [get] func (s *APIServer) ListApps(c *gin.Context) { envName := c.Param("envName") envMeta, err := env.GetEnvByName(envName) diff --git a/pkg/server/docs/.swagger-codegen-ignore b/pkg/server/docs/.swagger-codegen-ignore new file mode 100644 index 000000000..c5fa491b4 --- /dev/null +++ b/pkg/server/docs/.swagger-codegen-ignore @@ -0,0 +1,23 @@ +# Swagger Codegen Ignore +# Generated by swagger-codegen https://github.com/swagger-api/swagger-codegen + +# Use this file to prevent files from being overwritten by the generator. +# The patterns follow closely to .gitignore or .dockerignore. + +# As an example, the C# client generator defines ApiClient.cs. +# You can make changes and tell Swagger Codgen to ignore just this file by uncommenting the following line: +#ApiClient.cs + +# You can match any string of characters against a directory, file or extension with a single asterisk (*): +#foo/*/qux +# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux + +# You can recursively match patterns against a directory, file or extension with a double asterisk (**): +#foo/**/qux +# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux + +# You can also negate patterns with an exclamation (!). +# For example, you can ignore all files in a docs folder with the file extension .md: +#docs/*.md +# Then explicitly reverse the ignore rule for a single file: +#!docs/README.md diff --git a/pkg/server/docs/.swagger-codegen/VERSION b/pkg/server/docs/.swagger-codegen/VERSION new file mode 100644 index 000000000..812aaafe6 --- /dev/null +++ b/pkg/server/docs/.swagger-codegen/VERSION @@ -0,0 +1 @@ +3.0.22 \ No newline at end of file diff --git a/pkg/server/docs/docs.go b/pkg/server/docs/docs.go index afa868ffe..c13fc0595 100644 --- a/pkg/server/docs/docs.go +++ b/pkg/server/docs/docs.go @@ -18,7 +18,15 @@ var doc = `{ "info": { "description": "{{.Description}}", "title": "{{.Title}}", - "contact": {}, + "contact": { + "name": "Slack #kubevela", + "url": "https://kubevela.io", + "email": "zzxwill@gmail.com" + }, + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + }, "version": "{{.Version}}" }, "host": "{{.Host}}", @@ -89,17 +97,6 @@ var doc = `{ "environments" ], "operationId": "createEnvironment", - "parameters": [ - { - "description": "body", - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/apis.Environment" - } - } - ], "responses": { "200": { "description": "OK", @@ -395,9 +392,131 @@ var doc = `{ } } } + }, + "/envs/{envName}/apps": { + "get": { + "tags": [ + "applications" + ], + "summary": "list all applications", + "operationId": "ListApplications", + "parameters": [ + { + "type": "string", + "description": "environment name", + "name": "envName", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/apis.Response" + }, + { + "type": "object", + "properties": { + "code": { + "type": "integer" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/definitions/apis.ApplicationMeta" + } + } + } + } + ] + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/apis.Response" + }, + { + "type": "object", + "properties": { + "code": { + "type": "integer" + }, + "data": { + "type": "string" + } + } + } + ] + } + } + } + } } }, "definitions": { + "apis.ApplicationMeta": { + "type": "object", + "properties": { + "components": { + "type": "array", + "items": { + "$ref": "#/definitions/apis.ComponentMeta" + } + }, + "createdTime": { + "type": "string" + }, + "name": { + "type": "string" + }, + "status": { + "type": "string" + } + } + }, + "apis.ComponentMeta": { + "type": "object", + "properties": { + "app": { + "type": "string" + }, + "createdTime": { + "type": "string" + }, + "name": { + "type": "string" + }, + "status": { + "type": "string" + }, + "traits": { + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.ComponentTrait" + } + }, + "traitsNames": { + "description": "TraitNames for ` + "`" + `vela comp ls` + "`" + `", + "type": "array", + "items": { + "type": "string" + } + }, + "workload": { + "type": "string" + }, + "workloadName": { + "description": "WorkloadName for ` + "`" + `vela comp ls` + "`" + `", + "type": "string" + } + } + }, "apis.Environment": { "type": "object", "required": [ @@ -440,6 +559,432 @@ var doc = `{ "type": "integer" } } + }, + "v1alpha2.ApplicationConfiguration": { + "type": "object", + "properties": { + "spec": { + "type": "object", + "$ref": "#/definitions/v1alpha2.ApplicationConfigurationSpec" + }, + "status": { + "type": "object", + "$ref": "#/definitions/v1alpha2.ApplicationConfigurationStatus" + } + } + }, + "v1alpha2.ApplicationConfigurationComponent": { + "type": "object", + "properties": { + "componentName": { + "description": "ComponentName specifies a component whose latest revision will be bind\nwith ApplicationConfiguration. When the spec of the referenced component\nchanges, ApplicationConfiguration will automatically migrate all trait\naffect from the prior revision to the new one. This is mutually exclusive\nwith RevisionName.\n+optional", + "type": "string" + }, + "dataInputs": { + "description": "DataInputs specify the data input sinks into this component.", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.DataInput" + } + }, + "dataOutputs": { + "description": "DataOutputs specify the data output sources from this component.", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.DataOutput" + } + }, + "parameterValues": { + "description": "ParameterValues specify values for the the specified component's\nparameters. Any parameter required by the component must be specified.\n+optional", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.ComponentParameterValue" + } + }, + "revisionName": { + "description": "RevisionName of a specific component revision to which to bind\nApplicationConfiguration. This is mutually exclusive with componentName.\n+optional", + "type": "string" + }, + "scopes": { + "description": "Scopes in which the specified component should exist.\n+optional", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.ComponentScope" + } + }, + "traits": { + "description": "Traits of the specified component.\n+optional", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.ComponentTrait" + } + } + } + }, + "v1alpha2.ApplicationConfigurationSpec": { + "type": "object", + "properties": { + "components": { + "description": "Components of which this ApplicationConfiguration consists. Each\ncomponent will be used to instantiate a workload.", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.ApplicationConfigurationComponent" + } + } + } + }, + "v1alpha2.ApplicationConfigurationStatus": { + "type": "object", + "properties": { + "dependency": { + "type": "object", + "$ref": "#/definitions/v1alpha2.DependencyStatus" + }, + "historyWorkloads": { + "description": "HistoryWorkloads will record history but still working revision workloads.", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.HistoryWorkload" + } + }, + "observedGeneration": { + "description": "The generation observed by the appConfig controller.\n+optional", + "type": "integer" + }, + "status": { + "description": "Status is a place holder for a customized controller to fill\nif it needs a single place to summarize the status of the entire application", + "type": "string" + }, + "workloads": { + "description": "Workloads created by this ApplicationConfiguration.", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.WorkloadStatus" + } + } + } + }, + "v1alpha2.Component": { + "type": "object", + "properties": { + "spec": { + "type": "object", + "$ref": "#/definitions/v1alpha2.ComponentSpec" + }, + "status": { + "type": "object", + "$ref": "#/definitions/v1alpha2.ComponentStatus" + } + } + }, + "v1alpha2.ComponentParameter": { + "type": "object", + "properties": { + "description": { + "description": "Description of this parameter.\n+optional", + "type": "string" + }, + "fieldPaths": { + "description": "FieldPaths specifies an array of fields within this Component's workload\nthat will be overwritten by the value of this parameter. The type of the\nparameter (e.g. int, string) is inferred from the type of these fields;\nAll fields must be of the same type. Fields are specified as JSON field\npaths without a leading dot, for example 'spec.replicas'.", + "type": "array", + "items": { + "type": "string" + } + }, + "name": { + "description": "Name of this parameter. OAM ApplicationConfigurations will specify\nparameter values using this name.", + "type": "string" + }, + "required": { + "description": "+kubebuilder:default:=false\nRequired specifies whether or not a value for this parameter must be\nsupplied when authoring an ApplicationConfiguration.\n+optional", + "type": "boolean" + } + } + }, + "v1alpha2.ComponentParameterValue": { + "type": "object", + "properties": { + "name": { + "description": "Name of the component parameter to set.", + "type": "string" + }, + "value": { + "description": "Value to set.", + "type": "string" + } + } + }, + "v1alpha2.ComponentScope": { + "type": "object", + "properties": { + "scopeRef": { + "description": "A ScopeReference must refer to an OAM scope resource.", + "type": "string" + } + } + }, + "v1alpha2.ComponentSpec": { + "type": "object", + "properties": { + "parameters": { + "description": "Parameters exposed by this component. ApplicationConfigurations that\nreference this component may specify values for these parameters, which\nwill in turn be injected into the embedded workload.\n+optional", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.ComponentParameter" + } + }, + "workload": { + "description": "A Workload that will be created for each ApplicationConfiguration that\nincludes this Component. Workload is an instance of a workloadDefinition.\nWe either use the GVK info or a special \"type\" field in the workload to associate\nthe content of the workload with its workloadDefinition\n+kubebuilder:validation:EmbeddedResource\n+kubebuilder:pruning:PreserveUnknownFields", + "type": "string" + } + } + }, + "v1alpha2.ComponentStatus": { + "type": "object", + "properties": { + "latestRevision": { + "description": "LatestRevision of component\n+optional", + "type": "object", + "$ref": "#/definitions/v1alpha2.Revision" + }, + "observedGeneration": { + "description": "The generation observed by the component controller.\n+optional", + "type": "integer" + } + } + }, + "v1alpha2.ComponentTrait": { + "type": "object", + "properties": { + "dataInputs": { + "description": "DataInputs specify the data input sinks into this trait.\n+optional", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.DataInput" + } + }, + "dataOutputs": { + "description": "DataOutputs specify the data output sources from this trait.\n+optional", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.DataOutput" + } + }, + "trait": { + "description": "A Trait that will be created for the component\n+kubebuilder:validation:EmbeddedResource\n+kubebuilder:pruning:PreserveUnknownFields", + "type": "string" + } + } + }, + "v1alpha2.ConditionRequirement": { + "type": "object", + "properties": { + "fieldPath": { + "description": "+optional\nFieldPath specifies got value from workload/trait object", + "type": "string" + }, + "op": { + "type": "string" + }, + "value": { + "description": "+optional\nValue specifies an expected value\nThis is mutually exclusive with ValueFrom", + "type": "string" + }, + "valueFrom": { + "description": "+optional\nValueFrom specifies expected value from AppConfig\nThis is mutually exclusive with Value", + "type": "object", + "$ref": "#/definitions/v1alpha2.ValueFrom" + } + } + }, + "v1alpha2.DataInput": { + "type": "object", + "properties": { + "toFieldPaths": { + "description": "ToFieldPaths specifies the field paths of an object to fill passed value.", + "type": "array", + "items": { + "type": "string" + } + }, + "valueFrom": { + "description": "ValueFrom specifies the value source.", + "type": "object", + "$ref": "#/definitions/v1alpha2.DataInputValueFrom" + } + } + }, + "v1alpha2.DataInputValueFrom": { + "type": "object", + "properties": { + "dataOutputName": { + "description": "DataOutputName matches a name of a DataOutput in the same AppConfig.", + "type": "string" + } + } + }, + "v1alpha2.DataOutput": { + "type": "object", + "properties": { + "conditions": { + "description": "Conditions specify the conditions that should be satisfied before emitting a data output.\nDifferent conditions are AND-ed together.\nIf no conditions is specified, it is by default to check output value not empty.\n+optional", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.ConditionRequirement" + } + }, + "fieldPath": { + "description": "FieldPath refers to the value of an object's field.", + "type": "string" + }, + "name": { + "description": "Name is the unique name of a DataOutput in an ApplicationConfiguration.", + "type": "string" + } + } + }, + "v1alpha2.DependencyFromObject": { + "type": "object", + "properties": { + "fieldPath": { + "type": "string" + } + } + }, + "v1alpha2.DependencyStatus": { + "type": "object", + "properties": { + "unsatisfied": { + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.UnstaifiedDependency" + } + } + } + }, + "v1alpha2.DependencyToObject": { + "type": "object", + "properties": { + "fieldPaths": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "v1alpha2.HistoryWorkload": { + "type": "object", + "properties": { + "revision": { + "description": "Revision of this workload", + "type": "string" + }, + "workloadRef": { + "description": "Reference to running workload.", + "type": "string" + } + } + }, + "v1alpha2.Revision": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "revision": { + "type": "integer" + } + } + }, + "v1alpha2.UnstaifiedDependency": { + "type": "object", + "properties": { + "from": { + "type": "object", + "$ref": "#/definitions/v1alpha2.DependencyFromObject" + }, + "reason": { + "type": "string" + }, + "to": { + "type": "object", + "$ref": "#/definitions/v1alpha2.DependencyToObject" + } + } + }, + "v1alpha2.ValueFrom": { + "type": "object", + "properties": { + "fieldPath": { + "type": "string" + } + } + }, + "v1alpha2.WorkloadScope": { + "type": "object", + "properties": { + "scopeRef": { + "description": "Reference to a scope created by an ApplicationConfiguration.", + "type": "string" + }, + "status": { + "description": "Status is a place holder for a customized controller to fill\nif it needs a single place to summarize the status of the scope", + "type": "string" + } + } + }, + "v1alpha2.WorkloadStatus": { + "type": "object", + "properties": { + "componentName": { + "description": "ComponentName that produced this workload.", + "type": "string" + }, + "componentRevisionName": { + "description": "ComponentRevisionName of current component", + "type": "string" + }, + "scopes": { + "description": "Scopes associated with this workload.", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.WorkloadScope" + } + }, + "status": { + "description": "Status is a place holder for a customized controller to fill\nif it needs a single place to summarize the entire status of the workload", + "type": "string" + }, + "traits": { + "description": "Traits associated with this workload.", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.WorkloadTrait" + } + }, + "workloadRef": { + "description": "Reference to a workload created by an ApplicationConfiguration.", + "type": "string" + } + } + }, + "v1alpha2.WorkloadTrait": { + "type": "object", + "properties": { + "message": { + "description": "Message will allow controller to leave some additional information for this trait", + "type": "string" + }, + "status": { + "description": "Status is a place holder for a customized controller to fill\nif it needs a single place to summarize the status of the trait", + "type": "string" + }, + "traitRef": { + "description": "Reference to a trait created by an ApplicationConfiguration.", + "type": "string" + } + } } } }` @@ -456,11 +1001,11 @@ type swaggerInfo struct { // SwaggerInfo holds exported Swagger Info so clients can modify it var SwaggerInfo = swaggerInfo{ Version: "0.0.1", - Host: "", + Host: "127.0.0.1:38081", BasePath: "/api", Schemes: []string{}, - Title: "KubeVela API", - Description: "An KubeVela API.", + Title: "KubeVela Restful API", + Description: "KubeVela OpenAPI for applications/workloads/operating", } type s struct{} diff --git a/pkg/server/docs/swagger.json b/pkg/server/docs/swagger.json index cd7a37973..0b2f88431 100644 --- a/pkg/server/docs/swagger.json +++ b/pkg/server/docs/swagger.json @@ -1,11 +1,20 @@ { "swagger": "2.0", "info": { - "description": "An KubeVela API.", - "title": "KubeVela API", - "contact": {}, + "description": "KubeVela OpenAPI for applications/workloads/operating", + "title": "KubeVela Restful API", + "contact": { + "name": "Slack #kubevela", + "url": "https://kubevela.io", + "email": "zzxwill@gmail.com" + }, + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + }, "version": "0.0.1" }, + "host": "127.0.0.1:38081", "basePath": "/api", "paths": { "/envs/": { @@ -73,17 +82,6 @@ "environments" ], "operationId": "createEnvironment", - "parameters": [ - { - "description": "body", - "name": "body", - "in": "body", - "required": true, - "schema": { - "$ref": "#/definitions/apis.Environment" - } - } - ], "responses": { "200": { "description": "OK", @@ -379,9 +377,131 @@ } } } + }, + "/envs/{envName}/apps": { + "get": { + "tags": [ + "applications" + ], + "summary": "list all applications", + "operationId": "ListApplications", + "parameters": [ + { + "type": "string", + "description": "environment name", + "name": "envName", + "in": "path", + "required": true + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/apis.Response" + }, + { + "type": "object", + "properties": { + "code": { + "type": "integer" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/definitions/apis.ApplicationMeta" + } + } + } + } + ] + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/apis.Response" + }, + { + "type": "object", + "properties": { + "code": { + "type": "integer" + }, + "data": { + "type": "string" + } + } + } + ] + } + } + } + } } }, "definitions": { + "apis.ApplicationMeta": { + "type": "object", + "properties": { + "components": { + "type": "array", + "items": { + "$ref": "#/definitions/apis.ComponentMeta" + } + }, + "createdTime": { + "type": "string" + }, + "name": { + "type": "string" + }, + "status": { + "type": "string" + } + } + }, + "apis.ComponentMeta": { + "type": "object", + "properties": { + "app": { + "type": "string" + }, + "createdTime": { + "type": "string" + }, + "name": { + "type": "string" + }, + "status": { + "type": "string" + }, + "traits": { + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.ComponentTrait" + } + }, + "traitsNames": { + "description": "TraitNames for `vela comp ls`", + "type": "array", + "items": { + "type": "string" + } + }, + "workload": { + "type": "string" + }, + "workloadName": { + "description": "WorkloadName for `vela comp ls`", + "type": "string" + } + } + }, "apis.Environment": { "type": "object", "required": [ @@ -424,6 +544,432 @@ "type": "integer" } } + }, + "v1alpha2.ApplicationConfiguration": { + "type": "object", + "properties": { + "spec": { + "type": "object", + "$ref": "#/definitions/v1alpha2.ApplicationConfigurationSpec" + }, + "status": { + "type": "object", + "$ref": "#/definitions/v1alpha2.ApplicationConfigurationStatus" + } + } + }, + "v1alpha2.ApplicationConfigurationComponent": { + "type": "object", + "properties": { + "componentName": { + "description": "ComponentName specifies a component whose latest revision will be bind\nwith ApplicationConfiguration. When the spec of the referenced component\nchanges, ApplicationConfiguration will automatically migrate all trait\naffect from the prior revision to the new one. This is mutually exclusive\nwith RevisionName.\n+optional", + "type": "string" + }, + "dataInputs": { + "description": "DataInputs specify the data input sinks into this component.", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.DataInput" + } + }, + "dataOutputs": { + "description": "DataOutputs specify the data output sources from this component.", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.DataOutput" + } + }, + "parameterValues": { + "description": "ParameterValues specify values for the the specified component's\nparameters. Any parameter required by the component must be specified.\n+optional", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.ComponentParameterValue" + } + }, + "revisionName": { + "description": "RevisionName of a specific component revision to which to bind\nApplicationConfiguration. This is mutually exclusive with componentName.\n+optional", + "type": "string" + }, + "scopes": { + "description": "Scopes in which the specified component should exist.\n+optional", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.ComponentScope" + } + }, + "traits": { + "description": "Traits of the specified component.\n+optional", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.ComponentTrait" + } + } + } + }, + "v1alpha2.ApplicationConfigurationSpec": { + "type": "object", + "properties": { + "components": { + "description": "Components of which this ApplicationConfiguration consists. Each\ncomponent will be used to instantiate a workload.", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.ApplicationConfigurationComponent" + } + } + } + }, + "v1alpha2.ApplicationConfigurationStatus": { + "type": "object", + "properties": { + "dependency": { + "type": "object", + "$ref": "#/definitions/v1alpha2.DependencyStatus" + }, + "historyWorkloads": { + "description": "HistoryWorkloads will record history but still working revision workloads.", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.HistoryWorkload" + } + }, + "observedGeneration": { + "description": "The generation observed by the appConfig controller.\n+optional", + "type": "integer" + }, + "status": { + "description": "Status is a place holder for a customized controller to fill\nif it needs a single place to summarize the status of the entire application", + "type": "string" + }, + "workloads": { + "description": "Workloads created by this ApplicationConfiguration.", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.WorkloadStatus" + } + } + } + }, + "v1alpha2.Component": { + "type": "object", + "properties": { + "spec": { + "type": "object", + "$ref": "#/definitions/v1alpha2.ComponentSpec" + }, + "status": { + "type": "object", + "$ref": "#/definitions/v1alpha2.ComponentStatus" + } + } + }, + "v1alpha2.ComponentParameter": { + "type": "object", + "properties": { + "description": { + "description": "Description of this parameter.\n+optional", + "type": "string" + }, + "fieldPaths": { + "description": "FieldPaths specifies an array of fields within this Component's workload\nthat will be overwritten by the value of this parameter. The type of the\nparameter (e.g. int, string) is inferred from the type of these fields;\nAll fields must be of the same type. Fields are specified as JSON field\npaths without a leading dot, for example 'spec.replicas'.", + "type": "array", + "items": { + "type": "string" + } + }, + "name": { + "description": "Name of this parameter. OAM ApplicationConfigurations will specify\nparameter values using this name.", + "type": "string" + }, + "required": { + "description": "+kubebuilder:default:=false\nRequired specifies whether or not a value for this parameter must be\nsupplied when authoring an ApplicationConfiguration.\n+optional", + "type": "boolean" + } + } + }, + "v1alpha2.ComponentParameterValue": { + "type": "object", + "properties": { + "name": { + "description": "Name of the component parameter to set.", + "type": "string" + }, + "value": { + "description": "Value to set.", + "type": "string" + } + } + }, + "v1alpha2.ComponentScope": { + "type": "object", + "properties": { + "scopeRef": { + "description": "A ScopeReference must refer to an OAM scope resource.", + "type": "string" + } + } + }, + "v1alpha2.ComponentSpec": { + "type": "object", + "properties": { + "parameters": { + "description": "Parameters exposed by this component. ApplicationConfigurations that\nreference this component may specify values for these parameters, which\nwill in turn be injected into the embedded workload.\n+optional", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.ComponentParameter" + } + }, + "workload": { + "description": "A Workload that will be created for each ApplicationConfiguration that\nincludes this Component. Workload is an instance of a workloadDefinition.\nWe either use the GVK info or a special \"type\" field in the workload to associate\nthe content of the workload with its workloadDefinition\n+kubebuilder:validation:EmbeddedResource\n+kubebuilder:pruning:PreserveUnknownFields", + "type": "string" + } + } + }, + "v1alpha2.ComponentStatus": { + "type": "object", + "properties": { + "latestRevision": { + "description": "LatestRevision of component\n+optional", + "type": "object", + "$ref": "#/definitions/v1alpha2.Revision" + }, + "observedGeneration": { + "description": "The generation observed by the component controller.\n+optional", + "type": "integer" + } + } + }, + "v1alpha2.ComponentTrait": { + "type": "object", + "properties": { + "dataInputs": { + "description": "DataInputs specify the data input sinks into this trait.\n+optional", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.DataInput" + } + }, + "dataOutputs": { + "description": "DataOutputs specify the data output sources from this trait.\n+optional", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.DataOutput" + } + }, + "trait": { + "description": "A Trait that will be created for the component\n+kubebuilder:validation:EmbeddedResource\n+kubebuilder:pruning:PreserveUnknownFields", + "type": "string" + } + } + }, + "v1alpha2.ConditionRequirement": { + "type": "object", + "properties": { + "fieldPath": { + "description": "+optional\nFieldPath specifies got value from workload/trait object", + "type": "string" + }, + "op": { + "type": "string" + }, + "value": { + "description": "+optional\nValue specifies an expected value\nThis is mutually exclusive with ValueFrom", + "type": "string" + }, + "valueFrom": { + "description": "+optional\nValueFrom specifies expected value from AppConfig\nThis is mutually exclusive with Value", + "type": "object", + "$ref": "#/definitions/v1alpha2.ValueFrom" + } + } + }, + "v1alpha2.DataInput": { + "type": "object", + "properties": { + "toFieldPaths": { + "description": "ToFieldPaths specifies the field paths of an object to fill passed value.", + "type": "array", + "items": { + "type": "string" + } + }, + "valueFrom": { + "description": "ValueFrom specifies the value source.", + "type": "object", + "$ref": "#/definitions/v1alpha2.DataInputValueFrom" + } + } + }, + "v1alpha2.DataInputValueFrom": { + "type": "object", + "properties": { + "dataOutputName": { + "description": "DataOutputName matches a name of a DataOutput in the same AppConfig.", + "type": "string" + } + } + }, + "v1alpha2.DataOutput": { + "type": "object", + "properties": { + "conditions": { + "description": "Conditions specify the conditions that should be satisfied before emitting a data output.\nDifferent conditions are AND-ed together.\nIf no conditions is specified, it is by default to check output value not empty.\n+optional", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.ConditionRequirement" + } + }, + "fieldPath": { + "description": "FieldPath refers to the value of an object's field.", + "type": "string" + }, + "name": { + "description": "Name is the unique name of a DataOutput in an ApplicationConfiguration.", + "type": "string" + } + } + }, + "v1alpha2.DependencyFromObject": { + "type": "object", + "properties": { + "fieldPath": { + "type": "string" + } + } + }, + "v1alpha2.DependencyStatus": { + "type": "object", + "properties": { + "unsatisfied": { + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.UnstaifiedDependency" + } + } + } + }, + "v1alpha2.DependencyToObject": { + "type": "object", + "properties": { + "fieldPaths": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "v1alpha2.HistoryWorkload": { + "type": "object", + "properties": { + "revision": { + "description": "Revision of this workload", + "type": "string" + }, + "workloadRef": { + "description": "Reference to running workload.", + "type": "string" + } + } + }, + "v1alpha2.Revision": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "revision": { + "type": "integer" + } + } + }, + "v1alpha2.UnstaifiedDependency": { + "type": "object", + "properties": { + "from": { + "type": "object", + "$ref": "#/definitions/v1alpha2.DependencyFromObject" + }, + "reason": { + "type": "string" + }, + "to": { + "type": "object", + "$ref": "#/definitions/v1alpha2.DependencyToObject" + } + } + }, + "v1alpha2.ValueFrom": { + "type": "object", + "properties": { + "fieldPath": { + "type": "string" + } + } + }, + "v1alpha2.WorkloadScope": { + "type": "object", + "properties": { + "scopeRef": { + "description": "Reference to a scope created by an ApplicationConfiguration.", + "type": "string" + }, + "status": { + "description": "Status is a place holder for a customized controller to fill\nif it needs a single place to summarize the status of the scope", + "type": "string" + } + } + }, + "v1alpha2.WorkloadStatus": { + "type": "object", + "properties": { + "componentName": { + "description": "ComponentName that produced this workload.", + "type": "string" + }, + "componentRevisionName": { + "description": "ComponentRevisionName of current component", + "type": "string" + }, + "scopes": { + "description": "Scopes associated with this workload.", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.WorkloadScope" + } + }, + "status": { + "description": "Status is a place holder for a customized controller to fill\nif it needs a single place to summarize the entire status of the workload", + "type": "string" + }, + "traits": { + "description": "Traits associated with this workload.", + "type": "array", + "items": { + "$ref": "#/definitions/v1alpha2.WorkloadTrait" + } + }, + "workloadRef": { + "description": "Reference to a workload created by an ApplicationConfiguration.", + "type": "string" + } + } + }, + "v1alpha2.WorkloadTrait": { + "type": "object", + "properties": { + "message": { + "description": "Message will allow controller to leave some additional information for this trait", + "type": "string" + }, + "status": { + "description": "Status is a place holder for a customized controller to fill\nif it needs a single place to summarize the status of the trait", + "type": "string" + }, + "traitRef": { + "description": "Reference to a trait created by an ApplicationConfiguration.", + "type": "string" + } + } } } } \ No newline at end of file diff --git a/pkg/server/docs/swagger.yaml b/pkg/server/docs/swagger.yaml index 79d520926..bfe5f8ce7 100644 --- a/pkg/server/docs/swagger.yaml +++ b/pkg/server/docs/swagger.yaml @@ -1,5 +1,43 @@ basePath: /api definitions: + apis.ApplicationMeta: + properties: + components: + items: + $ref: '#/definitions/apis.ComponentMeta' + type: array + createdTime: + type: string + name: + type: string + status: + type: string + type: object + apis.ComponentMeta: + properties: + app: + type: string + createdTime: + type: string + name: + type: string + status: + type: string + traits: + items: + $ref: '#/definitions/v1alpha2.ComponentTrait' + type: array + traitsNames: + description: TraitNames for `vela comp ls` + items: + type: string + type: array + workload: + type: string + workloadName: + description: WorkloadName for `vela comp ls` + type: string + type: object apis.Environment: properties: current: @@ -28,10 +66,386 @@ definitions: code: type: integer type: object + v1alpha2.ApplicationConfiguration: + properties: + spec: + $ref: '#/definitions/v1alpha2.ApplicationConfigurationSpec' + type: object + status: + $ref: '#/definitions/v1alpha2.ApplicationConfigurationStatus' + type: object + type: object + v1alpha2.ApplicationConfigurationComponent: + properties: + componentName: + description: |- + ComponentName specifies a component whose latest revision will be bind + with ApplicationConfiguration. When the spec of the referenced component + changes, ApplicationConfiguration will automatically migrate all trait + affect from the prior revision to the new one. This is mutually exclusive + with RevisionName. + +optional + type: string + dataInputs: + description: DataInputs specify the data input sinks into this component. + items: + $ref: '#/definitions/v1alpha2.DataInput' + type: array + dataOutputs: + description: DataOutputs specify the data output sources from this component. + items: + $ref: '#/definitions/v1alpha2.DataOutput' + type: array + parameterValues: + description: |- + ParameterValues specify values for the the specified component's + parameters. Any parameter required by the component must be specified. + +optional + items: + $ref: '#/definitions/v1alpha2.ComponentParameterValue' + type: array + revisionName: + description: |- + RevisionName of a specific component revision to which to bind + ApplicationConfiguration. This is mutually exclusive with componentName. + +optional + type: string + scopes: + description: |- + Scopes in which the specified component should exist. + +optional + items: + $ref: '#/definitions/v1alpha2.ComponentScope' + type: array + traits: + description: |- + Traits of the specified component. + +optional + items: + $ref: '#/definitions/v1alpha2.ComponentTrait' + type: array + type: object + v1alpha2.ApplicationConfigurationSpec: + properties: + components: + description: |- + Components of which this ApplicationConfiguration consists. Each + component will be used to instantiate a workload. + items: + $ref: '#/definitions/v1alpha2.ApplicationConfigurationComponent' + type: array + type: object + v1alpha2.ApplicationConfigurationStatus: + properties: + dependency: + $ref: '#/definitions/v1alpha2.DependencyStatus' + type: object + historyWorkloads: + description: HistoryWorkloads will record history but still working revision workloads. + items: + $ref: '#/definitions/v1alpha2.HistoryWorkload' + type: array + observedGeneration: + description: |- + The generation observed by the appConfig controller. + +optional + type: integer + status: + description: |- + Status is a place holder for a customized controller to fill + if it needs a single place to summarize the status of the entire application + type: string + workloads: + description: Workloads created by this ApplicationConfiguration. + items: + $ref: '#/definitions/v1alpha2.WorkloadStatus' + type: array + type: object + v1alpha2.Component: + properties: + spec: + $ref: '#/definitions/v1alpha2.ComponentSpec' + type: object + status: + $ref: '#/definitions/v1alpha2.ComponentStatus' + type: object + type: object + v1alpha2.ComponentParameter: + properties: + description: + description: |- + Description of this parameter. + +optional + type: string + fieldPaths: + description: |- + FieldPaths specifies an array of fields within this Component's workload + that will be overwritten by the value of this parameter. The type of the + parameter (e.g. int, string) is inferred from the type of these fields; + All fields must be of the same type. Fields are specified as JSON field + paths without a leading dot, for example 'spec.replicas'. + items: + type: string + type: array + name: + description: |- + Name of this parameter. OAM ApplicationConfigurations will specify + parameter values using this name. + type: string + required: + description: |- + +kubebuilder:default:=false + Required specifies whether or not a value for this parameter must be + supplied when authoring an ApplicationConfiguration. + +optional + type: boolean + type: object + v1alpha2.ComponentParameterValue: + properties: + name: + description: Name of the component parameter to set. + type: string + value: + description: Value to set. + type: string + type: object + v1alpha2.ComponentScope: + properties: + scopeRef: + description: A ScopeReference must refer to an OAM scope resource. + type: string + type: object + v1alpha2.ComponentSpec: + properties: + parameters: + description: |- + Parameters exposed by this component. ApplicationConfigurations that + reference this component may specify values for these parameters, which + will in turn be injected into the embedded workload. + +optional + items: + $ref: '#/definitions/v1alpha2.ComponentParameter' + type: array + workload: + description: |- + A Workload that will be created for each ApplicationConfiguration that + includes this Component. Workload is an instance of a workloadDefinition. + We either use the GVK info or a special "type" field in the workload to associate + the content of the workload with its workloadDefinition + +kubebuilder:validation:EmbeddedResource + +kubebuilder:pruning:PreserveUnknownFields + type: string + type: object + v1alpha2.ComponentStatus: + properties: + latestRevision: + $ref: '#/definitions/v1alpha2.Revision' + description: |- + LatestRevision of component + +optional + type: object + observedGeneration: + description: |- + The generation observed by the component controller. + +optional + type: integer + type: object + v1alpha2.ComponentTrait: + properties: + dataInputs: + description: |- + DataInputs specify the data input sinks into this trait. + +optional + items: + $ref: '#/definitions/v1alpha2.DataInput' + type: array + dataOutputs: + description: |- + DataOutputs specify the data output sources from this trait. + +optional + items: + $ref: '#/definitions/v1alpha2.DataOutput' + type: array + trait: + description: |- + A Trait that will be created for the component + +kubebuilder:validation:EmbeddedResource + +kubebuilder:pruning:PreserveUnknownFields + type: string + type: object + v1alpha2.ConditionRequirement: + properties: + fieldPath: + description: |- + +optional + FieldPath specifies got value from workload/trait object + type: string + op: + type: string + value: + description: |- + +optional + Value specifies an expected value + This is mutually exclusive with ValueFrom + type: string + valueFrom: + $ref: '#/definitions/v1alpha2.ValueFrom' + description: |- + +optional + ValueFrom specifies expected value from AppConfig + This is mutually exclusive with Value + type: object + type: object + v1alpha2.DataInput: + properties: + toFieldPaths: + description: ToFieldPaths specifies the field paths of an object to fill passed value. + items: + type: string + type: array + valueFrom: + $ref: '#/definitions/v1alpha2.DataInputValueFrom' + description: ValueFrom specifies the value source. + type: object + type: object + v1alpha2.DataInputValueFrom: + properties: + dataOutputName: + description: DataOutputName matches a name of a DataOutput in the same AppConfig. + type: string + type: object + v1alpha2.DataOutput: + properties: + conditions: + description: |- + Conditions specify the conditions that should be satisfied before emitting a data output. + Different conditions are AND-ed together. + If no conditions is specified, it is by default to check output value not empty. + +optional + items: + $ref: '#/definitions/v1alpha2.ConditionRequirement' + type: array + fieldPath: + description: FieldPath refers to the value of an object's field. + type: string + name: + description: Name is the unique name of a DataOutput in an ApplicationConfiguration. + type: string + type: object + v1alpha2.DependencyFromObject: + properties: + fieldPath: + type: string + type: object + v1alpha2.DependencyStatus: + properties: + unsatisfied: + items: + $ref: '#/definitions/v1alpha2.UnstaifiedDependency' + type: array + type: object + v1alpha2.DependencyToObject: + properties: + fieldPaths: + items: + type: string + type: array + type: object + v1alpha2.HistoryWorkload: + properties: + revision: + description: Revision of this workload + type: string + workloadRef: + description: Reference to running workload. + type: string + type: object + v1alpha2.Revision: + properties: + name: + type: string + revision: + type: integer + type: object + v1alpha2.UnstaifiedDependency: + properties: + from: + $ref: '#/definitions/v1alpha2.DependencyFromObject' + type: object + reason: + type: string + to: + $ref: '#/definitions/v1alpha2.DependencyToObject' + type: object + type: object + v1alpha2.ValueFrom: + properties: + fieldPath: + type: string + type: object + v1alpha2.WorkloadScope: + properties: + scopeRef: + description: Reference to a scope created by an ApplicationConfiguration. + type: string + status: + description: |- + Status is a place holder for a customized controller to fill + if it needs a single place to summarize the status of the scope + type: string + type: object + v1alpha2.WorkloadStatus: + properties: + componentName: + description: ComponentName that produced this workload. + type: string + componentRevisionName: + description: ComponentRevisionName of current component + type: string + scopes: + description: Scopes associated with this workload. + items: + $ref: '#/definitions/v1alpha2.WorkloadScope' + type: array + status: + description: |- + Status is a place holder for a customized controller to fill + if it needs a single place to summarize the entire status of the workload + type: string + traits: + description: Traits associated with this workload. + items: + $ref: '#/definitions/v1alpha2.WorkloadTrait' + type: array + workloadRef: + description: Reference to a workload created by an ApplicationConfiguration. + type: string + type: object + v1alpha2.WorkloadTrait: + properties: + message: + description: Message will allow controller to leave some additional information for this trait + type: string + status: + description: |- + Status is a place holder for a customized controller to fill + if it needs a single place to summarize the status of the trait + type: string + traitRef: + description: Reference to a trait created by an ApplicationConfiguration. + type: string + type: object +host: 127.0.0.1:38081 info: - contact: {} - description: An KubeVela API. - title: KubeVela API + contact: + email: zzxwill@gmail.com + name: 'Slack #kubevela' + url: https://kubevela.io + description: KubeVela OpenAPI for applications/workloads/operating + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html + title: KubeVela Restful API version: 0.0.1 paths: /envs/: @@ -70,13 +484,6 @@ paths: - environments post: operationId: createEnvironment - parameters: - - description: body - in: body - name: body - required: true - schema: - $ref: '#/definitions/apis.Environment' responses: "200": description: OK @@ -243,4 +650,41 @@ paths: type: object tags: - environments + /envs/{envName}/apps: + get: + operationId: ListApplications + parameters: + - description: environment name + in: path + name: envName + required: true + type: string + responses: + "200": + description: OK + schema: + allOf: + - $ref: '#/definitions/apis.Response' + - properties: + code: + type: integer + data: + items: + $ref: '#/definitions/apis.ApplicationMeta' + type: array + type: object + "500": + description: Internal Server Error + schema: + allOf: + - $ref: '#/definitions/apis.Response' + - properties: + code: + type: integer + data: + type: string + type: object + summary: list all applications + tags: + - applications swagger: "2.0" diff --git a/pkg/server/envHandlers.go b/pkg/server/envHandlers.go index 947f1084a..fc23720d5 100644 --- a/pkg/server/envHandlers.go +++ b/pkg/server/envHandlers.go @@ -13,7 +13,6 @@ import ( // CreateEnv creates an environment // @Tags environments // @ID createEnvironment -// @Param body body apis.Environment true "body" // @Success 200 {object} apis.Response{code=int,data=string} // @Failure 500 {object} apis.Response{code=int,data=string} // @Router /envs/ [post] diff --git a/pkg/server/route.go b/pkg/server/route.go index ed182b991..baddc5f1b 100644 --- a/pkg/server/route.go +++ b/pkg/server/route.go @@ -16,11 +16,17 @@ import ( "github.com/oam-dev/kubevela/pkg/server/util" ) -// setup the gin http server handler -// @title KubeVela API -// @version 0.0.1 +// setupRoute sets gin http server handler +// @title KubeVela Restful API // @description An KubeVela API. - +// @version 0.0.1 +// @description KubeVela OpenAPI for applications/workloads/operating +// @contact.name Slack #kubevela +// @contact.url https://kubevela.io +// @contact.email zzxwill@gmail.com +// @license.name Apache 2.0 +// @license.url http://www.apache.org/licenses/LICENSE-2.0.html +// @host 127.0.0.1:38081 // @BasePath /api func (s *APIServer) setupRoute(staticPath string) http.Handler { // if deploying static Dashboard, set the mode to `release`, or to `debug` diff --git a/pkg/server/util/api.go b/pkg/server/util/api.go index 56232af5f..87926991b 100644 --- a/pkg/server/util/api.go +++ b/pkg/server/util/api.go @@ -13,7 +13,7 @@ import ( var DefaultDashboardPort = ":38081" // DefaultAPIServerPort refers to the default port number of APIServer -const DefaultAPIServerPort = ":8081" +const DefaultAPIServerPort = ":38081" // AssembleResponse assembles response data to return func AssembleResponse(c *gin.Context, data interface{}, err error) {