From a21e99278dbf2888d1fd934ef0aa2e54ede364df Mon Sep 17 00:00:00 2001 From: consolethinks Date: Tue, 3 Dec 2024 17:03:43 +0100 Subject: [PATCH] add docs --- docs/docs.go | 278 ++++++++++++++++++-- docs/swagger.json | 278 ++++++++++++++++++-- docs/swagger.yaml | 192 ++++++++++++-- internal/webserver/api.go | 83 ++++-- internal/webserver/docs/docs.go | 363 +++++++++++++++++++++++++++ internal/webserver/docs/swagger.json | 334 ++++++++++++++++++++++++ internal/webserver/docs/swagger.yaml | 219 ++++++++++++++++ 7 files changed, 1675 insertions(+), 72 deletions(-) create mode 100644 internal/webserver/docs/docs.go create mode 100644 internal/webserver/docs/swagger.json create mode 100644 internal/webserver/docs/swagger.yaml diff --git a/docs/docs.go b/docs/docs.go index 0fb5cd9..ab68042 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -23,6 +23,56 @@ const docTemplate = `{ "host": "{{.Host}}", "basePath": "{{.BasePath}}", "paths": { + "/callback": { + "get": { + "description": "For handling the authorization code received from the OIDC provider", + "produces": [ + "text/plain" + ], + "tags": [ + "authentication" + ], + "parameters": [ + { + "type": "string", + "description": "OAuth2 authorization code", + "name": "code", + "in": "query", + "required": true + }, + { + "type": "string", + "description": "OAuth2 state param", + "name": "state", + "in": "query", + "required": true + } + ], + "responses": { + "302": { + "description": "Found", + "headers": { + "Location": { + "type": "string", + "description": "goes to '/'" + } + } + }, + "400": { + "description": "request error", + "schema": { + "type": "string" + } + }, + "500": { + "description": "server error", + "schema": { + "type": "string" + } + } + } + } + }, "/datasets": { "post": { "description": "Ingest a new dataset", @@ -30,20 +80,91 @@ const docTemplate = `{ "application/json" ], "produces": [ - "application/json" + "json text/plain" ], "tags": [ "datasets" ], - "responses": {} + "parameters": [ + { + "description": "the 'metaData' attribute should contain the full yaml formatted metadata of the ingested dataset", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/webserver.IngestorUiPostDatasetRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/webserver.DatasetControllerIngestDataset200JSONResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "string" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "type": "string" + } + } + } } }, - "/transfer": { + "/login": { "get": { - "description": "Get list of transfers. Optional use the transferId parameter to only get one item.", - "consumes": [ - "application/json" + "description": "\"Initiates the OIDC authorization flow.\"", + "tags": [ + "authentication" + ], + "responses": { + "302": { + "description": "Found", + "headers": { + "Location": { + "type": "string", + "description": "redirect link to IdP with query params" + } + } + } + } + } + }, + "/logout": { + "get": { + "description": "Ends user session by deleting the session cookie.", + "tags": [ + "authentication" ], + "responses": { + "302": { + "description": "Found", + "headers": { + "Location": { + "type": "string", + "description": "goes to '/'" + } + } + }, + "500": { + "description": "the cookie couldn't be deleted due to some error", + "schema": { + "type": "string" + } + } + } + } + }, + "/transfer": { + "get": { + "description": "\"Get list of transfers. Optional use the transferId parameter to only get one item.\"", "produces": [ "application/json" ], @@ -53,21 +174,37 @@ const docTemplate = `{ "parameters": [ { "type": "integer", + "description": "page of transfers", "name": "page", - "in": "path" + "in": "query" }, { "type": "integer", + "description": "number of elements per page", "name": "pageSize", - "in": "path" + "in": "query" }, { - "type": "string", + "type": "integer", + "description": "get specific transfer by id", "name": "transferId", - "in": "path" + "in": "query" } ], - "responses": {} + "responses": { + "200": { + "description": "returns the list of transfers", + "schema": { + "$ref": "#/definitions/webserver.TransferControllerGetTransfer200JSONResponse" + } + }, + "400": { + "description": "the request is invalid", + "schema": { + "type": "string" + } + } + } }, "delete": { "description": "Cancel a data transfer", @@ -80,22 +217,131 @@ const docTemplate = `{ "tags": [ "transfer" ], - "responses": {} + "parameters": [ + { + "description": "it contains the id to cancel", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/webserver.IngestorUiDeleteTransferRequest" + } + } + ], + "responses": { + "200": { + "description": "returns the status and id of the affected task", + "schema": { + "$ref": "#/definitions/webserver.TransferControllerDeleteTransfer200JSONResponse" + } + }, + "400": { + "description": "invalid request", + "schema": { + "type": "string" + } + } + } } }, "/version": { "get": { "description": "Get the used ingestor version", - "consumes": [ - "application/json" - ], "produces": [ "application/json" ], "tags": [ "other" ], - "responses": {} + "responses": { + "200": { + "description": "returns the version of the servedrf", + "schema": { + "$ref": "#/definitions/webserver.OtherControllerGetVersion200JSONResponse" + } + } + } + } + } + }, + "definitions": { + "webserver.DatasetControllerIngestDataset200JSONResponse": { + "type": "object", + "properties": { + "ingestId": { + "description": "IngestId The unique ingestion id of the dataset.", + "type": "string" + }, + "status": { + "description": "Status The status of the ingestion. Can be used to send a message back to the ui.", + "type": "string" + } + } + }, + "webserver.IngestorUiDeleteTransferRequest": { + "type": "object", + "properties": { + "ingestId": { + "description": "IngestId Ingestion id to abort the ingestion", + "type": "string" + } + } + }, + "webserver.IngestorUiGetTransferItem": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "transferId": { + "type": "string" + } + } + }, + "webserver.IngestorUiPostDatasetRequest": { + "type": "object", + "properties": { + "metaData": { + "description": "MetaData The metadata of the dataset.", + "type": "string" + } + } + }, + "webserver.OtherControllerGetVersion200JSONResponse": { + "type": "object", + "properties": { + "version": { + "description": "Version Version of the ingestor.", + "type": "string" + } + } + }, + "webserver.TransferControllerDeleteTransfer200JSONResponse": { + "type": "object", + "properties": { + "ingestId": { + "description": "IngestId Ingestion id to abort the ingestion", + "type": "string" + }, + "status": { + "description": "Status New status of the ingestion.", + "type": "string" + } + } + }, + "webserver.TransferControllerGetTransfer200JSONResponse": { + "type": "object", + "properties": { + "total": { + "description": "Total Total number of transfers.", + "type": "integer" + }, + "transfers": { + "type": "array", + "items": { + "$ref": "#/definitions/webserver.IngestorUiGetTransferItem" + } + } } } } diff --git a/docs/swagger.json b/docs/swagger.json index a8c5874..07fdbeb 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -12,6 +12,56 @@ } }, "paths": { + "/callback": { + "get": { + "description": "For handling the authorization code received from the OIDC provider", + "produces": [ + "text/plain" + ], + "tags": [ + "authentication" + ], + "parameters": [ + { + "type": "string", + "description": "OAuth2 authorization code", + "name": "code", + "in": "query", + "required": true + }, + { + "type": "string", + "description": "OAuth2 state param", + "name": "state", + "in": "query", + "required": true + } + ], + "responses": { + "302": { + "description": "Found", + "headers": { + "Location": { + "type": "string", + "description": "goes to '/'" + } + } + }, + "400": { + "description": "request error", + "schema": { + "type": "string" + } + }, + "500": { + "description": "server error", + "schema": { + "type": "string" + } + } + } + } + }, "/datasets": { "post": { "description": "Ingest a new dataset", @@ -19,20 +69,91 @@ "application/json" ], "produces": [ - "application/json" + "json text/plain" ], "tags": [ "datasets" ], - "responses": {} + "parameters": [ + { + "description": "the 'metaData' attribute should contain the full yaml formatted metadata of the ingested dataset", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/webserver.IngestorUiPostDatasetRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/webserver.DatasetControllerIngestDataset200JSONResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "string" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "type": "string" + } + } + } } }, - "/transfer": { + "/login": { "get": { - "description": "Get list of transfers. Optional use the transferId parameter to only get one item.", - "consumes": [ - "application/json" + "description": "\"Initiates the OIDC authorization flow.\"", + "tags": [ + "authentication" + ], + "responses": { + "302": { + "description": "Found", + "headers": { + "Location": { + "type": "string", + "description": "redirect link to IdP with query params" + } + } + } + } + } + }, + "/logout": { + "get": { + "description": "Ends user session by deleting the session cookie.", + "tags": [ + "authentication" ], + "responses": { + "302": { + "description": "Found", + "headers": { + "Location": { + "type": "string", + "description": "goes to '/'" + } + } + }, + "500": { + "description": "the cookie couldn't be deleted due to some error", + "schema": { + "type": "string" + } + } + } + } + }, + "/transfer": { + "get": { + "description": "\"Get list of transfers. Optional use the transferId parameter to only get one item.\"", "produces": [ "application/json" ], @@ -42,21 +163,37 @@ "parameters": [ { "type": "integer", + "description": "page of transfers", "name": "page", - "in": "path" + "in": "query" }, { "type": "integer", + "description": "number of elements per page", "name": "pageSize", - "in": "path" + "in": "query" }, { - "type": "string", + "type": "integer", + "description": "get specific transfer by id", "name": "transferId", - "in": "path" + "in": "query" } ], - "responses": {} + "responses": { + "200": { + "description": "returns the list of transfers", + "schema": { + "$ref": "#/definitions/webserver.TransferControllerGetTransfer200JSONResponse" + } + }, + "400": { + "description": "the request is invalid", + "schema": { + "type": "string" + } + } + } }, "delete": { "description": "Cancel a data transfer", @@ -69,22 +206,131 @@ "tags": [ "transfer" ], - "responses": {} + "parameters": [ + { + "description": "it contains the id to cancel", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/webserver.IngestorUiDeleteTransferRequest" + } + } + ], + "responses": { + "200": { + "description": "returns the status and id of the affected task", + "schema": { + "$ref": "#/definitions/webserver.TransferControllerDeleteTransfer200JSONResponse" + } + }, + "400": { + "description": "invalid request", + "schema": { + "type": "string" + } + } + } } }, "/version": { "get": { "description": "Get the used ingestor version", - "consumes": [ - "application/json" - ], "produces": [ "application/json" ], "tags": [ "other" ], - "responses": {} + "responses": { + "200": { + "description": "returns the version of the servedrf", + "schema": { + "$ref": "#/definitions/webserver.OtherControllerGetVersion200JSONResponse" + } + } + } + } + } + }, + "definitions": { + "webserver.DatasetControllerIngestDataset200JSONResponse": { + "type": "object", + "properties": { + "ingestId": { + "description": "IngestId The unique ingestion id of the dataset.", + "type": "string" + }, + "status": { + "description": "Status The status of the ingestion. Can be used to send a message back to the ui.", + "type": "string" + } + } + }, + "webserver.IngestorUiDeleteTransferRequest": { + "type": "object", + "properties": { + "ingestId": { + "description": "IngestId Ingestion id to abort the ingestion", + "type": "string" + } + } + }, + "webserver.IngestorUiGetTransferItem": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "transferId": { + "type": "string" + } + } + }, + "webserver.IngestorUiPostDatasetRequest": { + "type": "object", + "properties": { + "metaData": { + "description": "MetaData The metadata of the dataset.", + "type": "string" + } + } + }, + "webserver.OtherControllerGetVersion200JSONResponse": { + "type": "object", + "properties": { + "version": { + "description": "Version Version of the ingestor.", + "type": "string" + } + } + }, + "webserver.TransferControllerDeleteTransfer200JSONResponse": { + "type": "object", + "properties": { + "ingestId": { + "description": "IngestId Ingestion id to abort the ingestion", + "type": "string" + }, + "status": { + "description": "Status New status of the ingestion.", + "type": "string" + } + } + }, + "webserver.TransferControllerGetTransfer200JSONResponse": { + "type": "object", + "properties": { + "total": { + "description": "Total Total number of transfers.", + "type": "integer" + }, + "transfers": { + "type": "array", + "items": { + "$ref": "#/definitions/webserver.IngestorUiGetTransferItem" + } + } } } } diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 4fa975c..0a87166 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -1,3 +1,58 @@ +definitions: + webserver.DatasetControllerIngestDataset200JSONResponse: + properties: + ingestId: + description: IngestId The unique ingestion id of the dataset. + type: string + status: + description: Status The status of the ingestion. Can be used to send a message + back to the ui. + type: string + type: object + webserver.IngestorUiDeleteTransferRequest: + properties: + ingestId: + description: IngestId Ingestion id to abort the ingestion + type: string + type: object + webserver.IngestorUiGetTransferItem: + properties: + status: + type: string + transferId: + type: string + type: object + webserver.IngestorUiPostDatasetRequest: + properties: + metaData: + description: MetaData The metadata of the dataset. + type: string + type: object + webserver.OtherControllerGetVersion200JSONResponse: + properties: + version: + description: Version Version of the ingestor. + type: string + type: object + webserver.TransferControllerDeleteTransfer200JSONResponse: + properties: + ingestId: + description: IngestId Ingestion id to abort the ingestion + type: string + status: + description: Status New status of the ingestion. + type: string + type: object + webserver.TransferControllerGetTransfer200JSONResponse: + properties: + total: + description: Total Total number of transfers. + type: integer + transfers: + items: + $ref: '#/definitions/webserver.IngestorUiGetTransferItem' + type: array + type: object info: contact: email: spencer.bliven@psi.ch @@ -7,54 +62,161 @@ info: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html paths: + /callback: + get: + description: For handling the authorization code received from the OIDC provider + parameters: + - description: OAuth2 authorization code + in: query + name: code + required: true + type: string + - description: OAuth2 state param + in: query + name: state + required: true + type: string + produces: + - text/plain + responses: + "302": + description: Found + headers: + Location: + description: goes to '/' + type: string + "400": + description: request error + schema: + type: string + "500": + description: server error + schema: + type: string + tags: + - authentication /datasets: post: consumes: - application/json description: Ingest a new dataset + parameters: + - description: the 'metaData' attribute should contain the full yaml formatted + metadata of the ingested dataset + in: body + name: request + required: true + schema: + $ref: '#/definitions/webserver.IngestorUiPostDatasetRequest' produces: - - application/json - responses: {} + - json text/plain + responses: + "200": + description: OK + schema: + $ref: '#/definitions/webserver.DatasetControllerIngestDataset200JSONResponse' + "400": + description: Bad Request + schema: + type: string + "500": + description: Internal Server Error + schema: + type: string tags: - datasets + /login: + get: + description: '"Initiates the OIDC authorization flow."' + responses: + "302": + description: Found + headers: + Location: + description: redirect link to IdP with query params + type: string + tags: + - authentication + /logout: + get: + description: Ends user session by deleting the session cookie. + responses: + "302": + description: Found + headers: + Location: + description: goes to '/' + type: string + "500": + description: the cookie couldn't be deleted due to some error + schema: + type: string + tags: + - authentication /transfer: delete: consumes: - application/json description: Cancel a data transfer + parameters: + - description: it contains the id to cancel + in: body + name: request + required: true + schema: + $ref: '#/definitions/webserver.IngestorUiDeleteTransferRequest' produces: - application/json - responses: {} + responses: + "200": + description: returns the status and id of the affected task + schema: + $ref: '#/definitions/webserver.TransferControllerDeleteTransfer200JSONResponse' + "400": + description: invalid request + schema: + type: string tags: - transfer get: - consumes: - - application/json - description: Get list of transfers. Optional use the transferId parameter to - only get one item. + description: '"Get list of transfers. Optional use the transferId parameter + to only get one item."' parameters: - - in: path + - description: page of transfers + in: query name: page type: integer - - in: path + - description: number of elements per page + in: query name: pageSize type: integer - - in: path + - description: get specific transfer by id + in: query name: transferId - type: string + type: integer produces: - application/json - responses: {} + responses: + "200": + description: returns the list of transfers + schema: + $ref: '#/definitions/webserver.TransferControllerGetTransfer200JSONResponse' + "400": + description: the request is invalid + schema: + type: string tags: - transfer /version: get: - consumes: - - application/json description: Get the used ingestor version produces: - application/json - responses: {} + responses: + "200": + description: returns the version of the servedrf + schema: + $ref: '#/definitions/webserver.OtherControllerGetVersion200JSONResponse' tags: - other swagger: "2.0" diff --git a/internal/webserver/api.go b/internal/webserver/api.go index a40ef20..397c976 100644 --- a/internal/webserver/api.go +++ b/internal/webserver/api.go @@ -100,12 +100,15 @@ func NewIngestorWebServer(version string, taskQueue *core.TaskQueue, authConf ws // DatasetControllerIngestDataset implements ServerInterface. // -// @Description Ingest a new dataset -// @Tags datasets -// @Accept json -// @Produce json -// -// @Router /datasets [post] +// @Description Ingest a new dataset +// @Tags datasets +// @Accept json +// @Produce json text/plain +// @Param request body webserver.IngestorUiPostDatasetRequest true "the 'metaData' attribute should contain the full yaml formatted metadata of the ingested dataset" +// @Success 200 {object} webserver.DatasetControllerIngestDataset200JSONResponse +// @Failure 400 {string} string +// @Failure 500 {string} string +// @Router /datasets [post] func (i *IngestorWebServerImplemenation) DatasetControllerIngestDataset(ctx context.Context, request DatasetControllerIngestDatasetRequestObject) (DatasetControllerIngestDatasetResponseObject, error) { // get sourcefolder from metadata metadataString := *request.Body.MetaData @@ -141,12 +144,11 @@ func (i *IngestorWebServerImplemenation) DatasetControllerIngestDataset(ctx cont // OtherControllerGetVersion implements ServerInterface. // -// @Description Get the used ingestor version -// @Tags other -// @Accept json -// @Produce json -// -// @Router /version [get] +// @Description Get the used ingestor version +// @Tags other +// @Produce json +// @Success 200 {object} webserver.OtherControllerGetVersion200JSONResponse "returns the version of the servedrf" +// @Router /version [get] func (i *IngestorWebServerImplemenation) OtherControllerGetVersion(ctx context.Context, request OtherControllerGetVersionRequestObject) (OtherControllerGetVersionResponseObject, error) { return OtherControllerGetVersion200JSONResponse{ Version: &i.version, @@ -155,12 +157,14 @@ func (i *IngestorWebServerImplemenation) OtherControllerGetVersion(ctx context.C // TransferControllerDeleteTransfer implements ServerInterface. // -// @Description Cancel a data transfer -// @Tags transfer -// @Accept json -// @Produce json -// -// @Router /transfer [delete] +// @Description Cancel a data transfer +// @Tags transfer +// @Accept json +// @Produce json +// @Param request body webserver.IngestorUiDeleteTransferRequest true "it contains the id to cancel" +// @Success 200 {object} webserver.TransferControllerDeleteTransfer200JSONResponse "returns the status and id of the affected task" +// @Failure 400 {string} string "invalid request" +// @Router /transfer [delete] func (i *IngestorWebServerImplemenation) TransferControllerDeleteTransfer(ctx context.Context, request TransferControllerDeleteTransferRequestObject) (TransferControllerDeleteTransferResponseObject, error) { if request.Body.IngestId == nil { return TransferControllerDeleteTransfer400TextResponse("Ingest ID was not specified in the request"), nil @@ -186,13 +190,15 @@ func (i *IngestorWebServerImplemenation) TransferControllerDeleteTransfer(ctx co // TransferControllerGetTransfer implements ServerInterface. // -// @Description Get list of transfers. Optional use the transferId parameter to only get one item. -// @Tags transfer -// @Accept json -// @Produce json -// @param params path TransferControllerGetTransferParams true "params" -// -// @Router /transfer [get] +// @Description "Get list of transfers. Optional use the transferId parameter to only get one item." +// @Tags transfer +// @Produce json +// @Param page query int false "page of transfers" +// @Param pageSize query int false "number of elements per page" +// @Param transferId query int false "get specific transfer by id" +// @Success 200 {object} webserver.TransferControllerGetTransfer200JSONResponse "returns the list of transfers" +// @Failure 400 {string} string "the request is invalid" +// @Router /transfer [get] func (i *IngestorWebServerImplemenation) TransferControllerGetTransfer(ctx context.Context, request TransferControllerGetTransferRequestObject) (TransferControllerGetTransferResponseObject, error) { scopes := ctx.Value(OpenIDScopes) fmt.Println("scopes: ", scopes) @@ -278,6 +284,13 @@ func (i *IngestorWebServerImplemenation) TransferControllerGetTransfer(ctx conte return TransferControllerGetTransfer400TextResponse("Not enough parameters"), nil } +// GetLogin implements ServerInterface. +// +// @Description "Initiates the OIDC authorization flow." +// @Tags authentication +// @Success 302 +// @Header 302 {string} Location "redirect link to IdP with query params" +// @Router /login [get] func (i *IngestorWebServerImplemenation) GetLogin(ctx context.Context, request GetLoginRequestObject) (GetLoginResponseObject, error) { // auth code flow @@ -339,6 +352,18 @@ func (i *IngestorWebServerImplemenation) GetLogin(ctx context.Context, request G }, nil } +// GetCallback implements ServerInterface. +// +// @Description For handling the authorization code received from the OIDC provider +// @Tags authentication +// @Produce text/plain +// @Param code query string true "OAuth2 authorization code" +// @Param state query string true "OAuth2 state param" +// @Success 302 +// @Header 302 {string} Location "goes to '/'" +// @Failure 400 {string} string "request error" +// @Failure 500 {string} string "server error" +// @Router /callback [get] func (i *IngestorWebServerImplemenation) GetCallback(ctx context.Context, request GetCallbackRequestObject) (GetCallbackResponseObject, error) { // get sessions ginCtx := ctx.(*gin.Context) @@ -447,6 +472,14 @@ func (i *IngestorWebServerImplemenation) GetCallback(ctx context.Context, reques }, nil } +// GetLogout implements ServerInterface. +// +// @Description Ends user session by deleting the session cookie. +// @Tags authentication +// @Success 302 +// @Header 302 {string} Location "goes to '/'" +// @Failure 500 {string} string "the cookie couldn't be deleted due to some error" +// @Router /logout [get] func (i *IngestorWebServerImplemenation) GetLogout(ctx context.Context, request GetLogoutRequestObject) (GetLogoutResponseObject, error) { ginCtx, ok := ctx.(*gin.Context) if !ok { diff --git a/internal/webserver/docs/docs.go b/internal/webserver/docs/docs.go new file mode 100644 index 0000000..06dbaab --- /dev/null +++ b/internal/webserver/docs/docs.go @@ -0,0 +1,363 @@ +// Package docs Code generated by swaggo/swag. DO NOT EDIT +package docs + +import "github.com/swaggo/swag" + +const docTemplate = `{ + "schemes": {{ marshal .Schemes }}, + "swagger": "2.0", + "info": { + "description": "{{escape .Description}}", + "title": "{{.Title}}", + "contact": { + "name": "SwissOpenEM", + "url": "https://swissopenem.github.io", + "email": "spencer.bliven@psi.ch" + }, + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + }, + "version": "{{.Version}}" + }, + "host": "{{.Host}}", + "basePath": "{{.BasePath}}", + "paths": { + "/callback": { + "get": { + "description": "For handling the authorization code received from the OIDC provider", + "produces": [ + "text/plain" + ], + "tags": [ + "authentication" + ], + "parameters": [ + { + "type": "string", + "description": "OAuth2 authorization code", + "name": "code", + "in": "query", + "required": true + }, + { + "type": "string", + "description": "OAuth2 state param", + "name": "state", + "in": "query", + "required": true + } + ], + "responses": { + "302": { + "description": "Found", + "headers": { + "Location": { + "type": "string", + "description": "goes to '/'" + } + } + }, + "400": { + "description": "request error", + "schema": { + "type": "string" + } + }, + "500": { + "description": "server error", + "schema": { + "type": "string" + } + } + } + } + }, + "/datasets": { + "post": { + "description": "Ingest a new dataset", + "consumes": [ + "application/json" + ], + "produces": [ + "json text/plain" + ], + "tags": [ + "datasets" + ], + "parameters": [ + { + "description": "mainly contains the dataset metadata", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/webserver.DatasetControllerIngestDatasetRequestObject" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/webserver.DatasetControllerIngestDataset200JSONResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "string" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "type": "string" + } + } + } + } + }, + "/logout": { + "get": { + "description": "Ends user session by deleting the session cookie.", + "tags": [ + "authentication" + ], + "responses": { + "302": { + "description": "Found", + "headers": { + "Location": { + "type": "string", + "description": "goes to '/'" + } + } + }, + "500": { + "description": "can't delete cookie", + "schema": { + "type": "string" + } + } + } + } + }, + "/transfer": { + "get": { + "description": "\"Get list of transfers. Optional use the transferId parameter to only get one item.\"", + "produces": [ + "application/json" + ], + "tags": [ + "transfer" + ], + "parameters": [ + { + "type": "integer", + "description": "page of transfers", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "number of elements per page", + "name": "pageSize", + "in": "query" + }, + { + "type": "integer", + "description": "get specific transfer by id", + "name": "transferId", + "in": "query" + } + ], + "responses": { + "200": { + "description": "returns the list of transfers", + "schema": { + "$ref": "#/definitions/webserver.TransferControllerGetTransfer200JSONResponse" + } + }, + "400": { + "description": "the request is invalid", + "schema": { + "type": "string" + } + } + } + }, + "delete": { + "description": "Cancel a data transfer", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "transfer" + ], + "parameters": [ + { + "description": "it contains the id to cancel", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/webserver.TransferControllerDeleteTransferRequestObject" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/webserver.TransferControllerDeleteTransfer200JSONResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "string" + } + } + } + } + }, + "/version": { + "get": { + "description": "Get the used ingestor version", + "produces": [ + "application/json" + ], + "tags": [ + "other" + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/webserver.OtherControllerGetVersion200JSONResponse" + } + } + } + } + } + }, + "definitions": { + "webserver.DatasetControllerIngestDataset200JSONResponse": { + "type": "object", + "properties": { + "ingestId": { + "description": "IngestId The unique ingestion id of the dataset.", + "type": "string" + }, + "status": { + "description": "Status The status of the ingestion. Can be used to send a message back to the ui.", + "type": "string" + } + } + }, + "webserver.DatasetControllerIngestDatasetJSONRequestBody": { + "type": "object", + "properties": { + "metaData": { + "description": "MetaData The metadata of the dataset.", + "type": "string" + } + } + }, + "webserver.DatasetControllerIngestDatasetRequestObject": { + "type": "object", + "properties": { + "body": { + "$ref": "#/definitions/webserver.DatasetControllerIngestDatasetJSONRequestBody" + } + } + }, + "webserver.IngestorUiGetTransferItem": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "transferId": { + "type": "string" + } + } + }, + "webserver.OtherControllerGetVersion200JSONResponse": { + "type": "object", + "properties": { + "version": { + "description": "Version Version of the ingestor.", + "type": "string" + } + } + }, + "webserver.TransferControllerDeleteTransfer200JSONResponse": { + "type": "object", + "properties": { + "ingestId": { + "description": "IngestId Ingestion id to abort the ingestion", + "type": "string" + }, + "status": { + "description": "Status New status of the ingestion.", + "type": "string" + } + } + }, + "webserver.TransferControllerDeleteTransferJSONRequestBody": { + "type": "object", + "properties": { + "ingestId": { + "description": "IngestId Ingestion id to abort the ingestion", + "type": "string" + } + } + }, + "webserver.TransferControllerDeleteTransferRequestObject": { + "type": "object", + "properties": { + "body": { + "$ref": "#/definitions/webserver.TransferControllerDeleteTransferJSONRequestBody" + } + } + }, + "webserver.TransferControllerGetTransfer200JSONResponse": { + "type": "object", + "properties": { + "total": { + "description": "Total Total number of transfers.", + "type": "integer" + }, + "transfers": { + "type": "array", + "items": { + "$ref": "#/definitions/webserver.IngestorUiGetTransferItem" + } + } + } + } + } +}` + +// SwaggerInfo holds exported Swagger Info so clients can modify it +var SwaggerInfo = &swag.Spec{ + Version: "", + Host: "", + BasePath: "", + Schemes: []string{}, + Title: "", + Description: "", + InfoInstanceName: "swagger", + SwaggerTemplate: docTemplate, + LeftDelim: "{{", + RightDelim: "}}", +} + +func init() { + swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo) +} diff --git a/internal/webserver/docs/swagger.json b/internal/webserver/docs/swagger.json new file mode 100644 index 0000000..427b2a1 --- /dev/null +++ b/internal/webserver/docs/swagger.json @@ -0,0 +1,334 @@ +{ + "swagger": "2.0", + "info": { + "contact": { + "name": "SwissOpenEM", + "url": "https://swissopenem.github.io", + "email": "spencer.bliven@psi.ch" + }, + "license": { + "name": "Apache 2.0", + "url": "http://www.apache.org/licenses/LICENSE-2.0.html" + } + }, + "paths": { + "/callback": { + "get": { + "description": "For handling the authorization code received from the OIDC provider", + "produces": [ + "text/plain" + ], + "tags": [ + "authentication" + ], + "parameters": [ + { + "type": "string", + "description": "OAuth2 authorization code", + "name": "code", + "in": "query", + "required": true + }, + { + "type": "string", + "description": "OAuth2 state param", + "name": "state", + "in": "query", + "required": true + } + ], + "responses": { + "302": { + "description": "Found", + "headers": { + "Location": { + "type": "string", + "description": "goes to '/'" + } + } + }, + "400": { + "description": "request error", + "schema": { + "type": "string" + } + }, + "500": { + "description": "server error", + "schema": { + "type": "string" + } + } + } + } + }, + "/datasets": { + "post": { + "description": "Ingest a new dataset", + "consumes": [ + "application/json" + ], + "produces": [ + "json text/plain" + ], + "tags": [ + "datasets" + ], + "parameters": [ + { + "description": "mainly contains the dataset metadata", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/webserver.DatasetControllerIngestDatasetRequestObject" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/webserver.DatasetControllerIngestDataset200JSONResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "string" + } + }, + "500": { + "description": "Internal Server Error", + "schema": { + "type": "string" + } + } + } + } + }, + "/logout": { + "get": { + "description": "Ends user session by deleting the session cookie.", + "tags": [ + "authentication" + ], + "responses": { + "302": { + "description": "Found", + "headers": { + "Location": { + "type": "string", + "description": "goes to '/'" + } + } + }, + "500": { + "description": "can't delete cookie", + "schema": { + "type": "string" + } + } + } + } + }, + "/transfer": { + "get": { + "description": "\"Get list of transfers. Optional use the transferId parameter to only get one item.\"", + "produces": [ + "application/json" + ], + "tags": [ + "transfer" + ], + "parameters": [ + { + "type": "integer", + "description": "page of transfers", + "name": "page", + "in": "query" + }, + { + "type": "integer", + "description": "number of elements per page", + "name": "pageSize", + "in": "query" + }, + { + "type": "integer", + "description": "get specific transfer by id", + "name": "transferId", + "in": "query" + } + ], + "responses": { + "200": { + "description": "returns the list of transfers", + "schema": { + "$ref": "#/definitions/webserver.TransferControllerGetTransfer200JSONResponse" + } + }, + "400": { + "description": "the request is invalid", + "schema": { + "type": "string" + } + } + } + }, + "delete": { + "description": "Cancel a data transfer", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "transfer" + ], + "parameters": [ + { + "description": "it contains the id to cancel", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/webserver.TransferControllerDeleteTransferRequestObject" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/webserver.TransferControllerDeleteTransfer200JSONResponse" + } + }, + "400": { + "description": "Bad Request", + "schema": { + "type": "string" + } + } + } + } + }, + "/version": { + "get": { + "description": "Get the used ingestor version", + "produces": [ + "application/json" + ], + "tags": [ + "other" + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "$ref": "#/definitions/webserver.OtherControllerGetVersion200JSONResponse" + } + } + } + } + } + }, + "definitions": { + "webserver.DatasetControllerIngestDataset200JSONResponse": { + "type": "object", + "properties": { + "ingestId": { + "description": "IngestId The unique ingestion id of the dataset.", + "type": "string" + }, + "status": { + "description": "Status The status of the ingestion. Can be used to send a message back to the ui.", + "type": "string" + } + } + }, + "webserver.DatasetControllerIngestDatasetJSONRequestBody": { + "type": "object", + "properties": { + "metaData": { + "description": "MetaData The metadata of the dataset.", + "type": "string" + } + } + }, + "webserver.DatasetControllerIngestDatasetRequestObject": { + "type": "object", + "properties": { + "body": { + "$ref": "#/definitions/webserver.DatasetControllerIngestDatasetJSONRequestBody" + } + } + }, + "webserver.IngestorUiGetTransferItem": { + "type": "object", + "properties": { + "status": { + "type": "string" + }, + "transferId": { + "type": "string" + } + } + }, + "webserver.OtherControllerGetVersion200JSONResponse": { + "type": "object", + "properties": { + "version": { + "description": "Version Version of the ingestor.", + "type": "string" + } + } + }, + "webserver.TransferControllerDeleteTransfer200JSONResponse": { + "type": "object", + "properties": { + "ingestId": { + "description": "IngestId Ingestion id to abort the ingestion", + "type": "string" + }, + "status": { + "description": "Status New status of the ingestion.", + "type": "string" + } + } + }, + "webserver.TransferControllerDeleteTransferJSONRequestBody": { + "type": "object", + "properties": { + "ingestId": { + "description": "IngestId Ingestion id to abort the ingestion", + "type": "string" + } + } + }, + "webserver.TransferControllerDeleteTransferRequestObject": { + "type": "object", + "properties": { + "body": { + "$ref": "#/definitions/webserver.TransferControllerDeleteTransferJSONRequestBody" + } + } + }, + "webserver.TransferControllerGetTransfer200JSONResponse": { + "type": "object", + "properties": { + "total": { + "description": "Total Total number of transfers.", + "type": "integer" + }, + "transfers": { + "type": "array", + "items": { + "$ref": "#/definitions/webserver.IngestorUiGetTransferItem" + } + } + } + } + } +} \ No newline at end of file diff --git a/internal/webserver/docs/swagger.yaml b/internal/webserver/docs/swagger.yaml new file mode 100644 index 0000000..cddd5ac --- /dev/null +++ b/internal/webserver/docs/swagger.yaml @@ -0,0 +1,219 @@ +definitions: + webserver.DatasetControllerIngestDataset200JSONResponse: + properties: + ingestId: + description: IngestId The unique ingestion id of the dataset. + type: string + status: + description: Status The status of the ingestion. Can be used to send a message + back to the ui. + type: string + type: object + webserver.DatasetControllerIngestDatasetJSONRequestBody: + properties: + metaData: + description: MetaData The metadata of the dataset. + type: string + type: object + webserver.DatasetControllerIngestDatasetRequestObject: + properties: + body: + $ref: '#/definitions/webserver.DatasetControllerIngestDatasetJSONRequestBody' + type: object + webserver.IngestorUiGetTransferItem: + properties: + status: + type: string + transferId: + type: string + type: object + webserver.OtherControllerGetVersion200JSONResponse: + properties: + version: + description: Version Version of the ingestor. + type: string + type: object + webserver.TransferControllerDeleteTransfer200JSONResponse: + properties: + ingestId: + description: IngestId Ingestion id to abort the ingestion + type: string + status: + description: Status New status of the ingestion. + type: string + type: object + webserver.TransferControllerDeleteTransferJSONRequestBody: + properties: + ingestId: + description: IngestId Ingestion id to abort the ingestion + type: string + type: object + webserver.TransferControllerDeleteTransferRequestObject: + properties: + body: + $ref: '#/definitions/webserver.TransferControllerDeleteTransferJSONRequestBody' + type: object + webserver.TransferControllerGetTransfer200JSONResponse: + properties: + total: + description: Total Total number of transfers. + type: integer + transfers: + items: + $ref: '#/definitions/webserver.IngestorUiGetTransferItem' + type: array + type: object +info: + contact: + email: spencer.bliven@psi.ch + name: SwissOpenEM + url: https://swissopenem.github.io + license: + name: Apache 2.0 + url: http://www.apache.org/licenses/LICENSE-2.0.html +paths: + /callback: + get: + description: For handling the authorization code received from the OIDC provider + parameters: + - description: OAuth2 authorization code + in: query + name: code + required: true + type: string + - description: OAuth2 state param + in: query + name: state + required: true + type: string + produces: + - text/plain + responses: + "302": + description: Found + headers: + Location: + description: goes to '/' + type: string + "400": + description: request error + schema: + type: string + "500": + description: server error + schema: + type: string + tags: + - authentication + /datasets: + post: + consumes: + - application/json + description: Ingest a new dataset + parameters: + - description: mainly contains the dataset metadata + in: body + name: request + required: true + schema: + $ref: '#/definitions/webserver.DatasetControllerIngestDatasetRequestObject' + produces: + - json text/plain + responses: + "200": + description: OK + schema: + $ref: '#/definitions/webserver.DatasetControllerIngestDataset200JSONResponse' + "400": + description: Bad Request + schema: + type: string + "500": + description: Internal Server Error + schema: + type: string + tags: + - datasets + /logout: + get: + description: Ends user session by deleting the session cookie. + responses: + "302": + description: Found + headers: + Location: + description: goes to '/' + type: string + "500": + description: can't delete cookie + schema: + type: string + tags: + - authentication + /transfer: + delete: + consumes: + - application/json + description: Cancel a data transfer + parameters: + - description: it contains the id to cancel + in: body + name: request + required: true + schema: + $ref: '#/definitions/webserver.TransferControllerDeleteTransferRequestObject' + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/webserver.TransferControllerDeleteTransfer200JSONResponse' + "400": + description: Bad Request + schema: + type: string + tags: + - transfer + get: + description: '"Get list of transfers. Optional use the transferId parameter + to only get one item."' + parameters: + - description: page of transfers + in: query + name: page + type: integer + - description: number of elements per page + in: query + name: pageSize + type: integer + - description: get specific transfer by id + in: query + name: transferId + type: integer + produces: + - application/json + responses: + "200": + description: returns the list of transfers + schema: + $ref: '#/definitions/webserver.TransferControllerGetTransfer200JSONResponse' + "400": + description: the request is invalid + schema: + type: string + tags: + - transfer + /version: + get: + description: Get the used ingestor version + produces: + - application/json + responses: + "200": + description: OK + schema: + $ref: '#/definitions/webserver.OtherControllerGetVersion200JSONResponse' + tags: + - other +swagger: "2.0"