From 2b546ed7001a06094504daf1ccd691f8d5d1611e Mon Sep 17 00:00:00 2001 From: Pavel Bezliapovich Date: Fri, 4 Oct 2024 09:41:45 +0200 Subject: [PATCH] chore: Added OpenAPIInfo Refs: #40 --- docs/openapi.json | 565 +++++++++--------- .../rest/controller/OpenAPIInfo.java | 17 + 2 files changed, 300 insertions(+), 282 deletions(-) create mode 100644 src/main/java/ch/sbb/polarion/extension/excel_importer/rest/controller/OpenAPIInfo.java diff --git a/docs/openapi.json b/docs/openapi.json index 2312465..eda1f14 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -1,17 +1,35 @@ { "openapi" : "3.0.1", "info" : { - "title" : "REST API" + "title" : "Excel Importer REST API", + "version" : "v1" }, "paths" : { + "/api/context" : { + "get" : { + "operationId" : "getContext", + "responses" : { + "default" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Context" + } + } + }, + "description" : "Context information" + } + }, + "summary" : "Returns basic context information of Polarion's extension", + "tags" : [ "Extension Information" ] + } + }, "/api/projects/{projectId}/import" : { "post" : { - "tags" : [ "Excel Import" ], - "summary" : "Imports Excel sheet", "operationId" : "importExcelSheet", "parameters" : [ { - "name" : "projectId", "in" : "path", + "name" : "projectId", "required" : true, "schema" : { "type" : "string" @@ -23,13 +41,13 @@ "schema" : { "type" : "object", "properties" : { - "mappingName" : { - "type" : "string", - "default" : "Default" - }, "file" : { "type" : "string", "format" : "binary" + }, + "mappingName" : { + "type" : "string", + "default" : "Default" } } } @@ -38,33 +56,26 @@ }, "responses" : { "200" : { - "description" : "Successful import", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ImportResult" } } - } + }, + "description" : "Successful import" } - } + }, + "summary" : "Imports Excel sheet", + "tags" : [ "Excel Import" ] } }, - "/api/projects/{projectId}/workitem_types/{workItemType}/fields" : { + "/api/projects/{projectId}/workitem_types" : { "get" : { - "tags" : [ "WorkItems" ], - "summary" : "Get all fields for requested project and workitem type", - "operationId" : "getWorkItemFields", + "operationId" : "getWorkItemTypes", "parameters" : [ { - "name" : "projectId", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } - }, { - "name" : "workItemType", "in" : "path", + "name" : "projectId", "required" : true, "schema" : { "type" : "string" @@ -72,26 +83,33 @@ } ], "responses" : { "200" : { - "description" : "Successfully retrieved fields", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/FieldMetadata" + "$ref" : "#/components/schemas/ITypeOpt" } } - } + }, + "description" : "Successfully retrieved work item types" } - } + }, + "summary" : "Get workitem types for project", + "tags" : [ "WorkItems" ] } }, - "/api/projects/{projectId}/workitem_types" : { + "/api/projects/{projectId}/workitem_types/{workItemType}/fields" : { "get" : { - "tags" : [ "WorkItems" ], - "summary" : "Get workitem types for project", - "operationId" : "getWorkItemTypes", + "operationId" : "getWorkItemFields", "parameters" : [ { + "in" : "path", "name" : "projectId", + "required" : true, + "schema" : { + "type" : "string" + } + }, { "in" : "path", + "name" : "workItemType", "required" : true, "schema" : { "type" : "string" @@ -99,105 +117,106 @@ } ], "responses" : { "200" : { - "description" : "Successfully retrieved work item types", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/ITypeOpt" + "$ref" : "#/components/schemas/FieldMetadata" } } - } + }, + "description" : "Successfully retrieved fields" } - } + }, + "summary" : "Get all fields for requested project and workitem type", + "tags" : [ "WorkItems" ] } }, - "/api/context" : { + "/api/settings" : { "get" : { - "tags" : [ "Extension Information" ], - "summary" : "Returns basic context information of Polarion's extension", - "operationId" : "getContext", + "operationId" : "readFeaturesList_1", "responses" : { "default" : { - "description" : "Context information", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Context" + "type" : "string" } } - } + }, + "description" : "List of supported features" } - } + }, + "summary" : "Returns the complete list of all supported features", + "tags" : [ "Settings" ] } }, - "/api/version" : { + "/api/settings/{feature}/default-content" : { "get" : { - "tags" : [ "Extension Information" ], - "summary" : "Returns version of Polarion's extension", - "operationId" : "getVersion", + "operationId" : "getDefaultValues_1", + "parameters" : [ { + "in" : "path", + "name" : "feature", + "required" : true, + "schema" : { + "type" : "string" + } + } ], "responses" : { "default" : { - "description" : "Version information", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/Version" + "$ref" : "#/components/schemas/SettingsModel" } } - } + }, + "description" : "Default values" } - } + }, + "summary" : "Returns default values of specified setting", + "tags" : [ "Settings" ] } }, - "/api/settings/{feature}/names/{name}" : { - "post" : { - "tags" : [ "Settings" ], - "summary" : "Updates name of specified named setting", - "operationId" : "renameSetting_1", + "/api/settings/{feature}/names" : { + "get" : { + "operationId" : "readSettingNames_1", "parameters" : [ { - "name" : "feature", - "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } - }, { - "name" : "name", "in" : "path", + "name" : "feature", "required" : true, "schema" : { "type" : "string" } } ], - "requestBody" : { - "content" : { - "application/json" : { - "schema" : { - "type" : "string" + "responses" : { + "default" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/SettingName" + } } - } + }, + "description" : "List of setting names" } }, - "responses" : { - "204" : { - "description" : "Setting name updated successfully" - } - } - }, + "summary" : "Returns names of specified setting", + "tags" : [ "Settings" ] + } + }, + "/api/settings/{feature}/names/{name}" : { "delete" : { - "tags" : [ "Settings" ], - "summary" : "Deletes specified setting by id", "operationId" : "deleteSetting_1", "parameters" : [ { - "name" : "feature", "in" : "path", + "name" : "feature", "required" : true, "schema" : { "type" : "string" } }, { - "name" : "name", "in" : "path", + "name" : "name", "required" : true, "schema" : { "type" : "string" @@ -207,142 +226,96 @@ "204" : { "description" : "Setting deleted successfully" } - } - } - }, - "/api/settings/{feature}/default-content" : { - "get" : { - "tags" : [ "Settings" ], - "summary" : "Returns default values of specified setting", - "operationId" : "getDefaultValues_1", + }, + "summary" : "Deletes specified setting by id", + "tags" : [ "Settings" ] + }, + "post" : { + "operationId" : "renameSetting_1", "parameters" : [ { - "name" : "feature", "in" : "path", - "required" : true, - "schema" : { - "type" : "string" - } - } ], - "responses" : { - "default" : { - "description" : "Default values", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/SettingsModel" - } - } - } - } - } - } - }, - "/api/settings" : { - "get" : { - "tags" : [ "Settings" ], - "summary" : "Returns the complete list of all supported features", - "operationId" : "readFeaturesList_1", - "responses" : { - "default" : { - "description" : "List of supported features", - "content" : { - "application/json" : { - "schema" : { - "type" : "string" - } - } - } - } - } - } - }, - "/api/settings/{feature}/names/{name}/revisions" : { - "get" : { - "tags" : [ "Settings" ], - "summary" : "Returns revisions history of specified setting with specified id", - "operationId" : "readRevisionsList_1", - "parameters" : [ { "name" : "feature", - "in" : "path", "required" : true, "schema" : { "type" : "string" } }, { - "name" : "name", "in" : "path", + "name" : "name", "required" : true, "schema" : { "type" : "string" } } ], - "responses" : { - "default" : { - "description" : "List of revisions", - "content" : { - "application/json" : { - "schema" : { - "$ref" : "#/components/schemas/Revision" - } + "requestBody" : { + "content" : { + "application/json" : { + "schema" : { + "type" : "string" } } } - } + }, + "responses" : { + "204" : { + "description" : "Setting name updated successfully" + } + }, + "summary" : "Updates name of specified named setting", + "tags" : [ "Settings" ] } }, "/api/settings/{feature}/names/{name}/content" : { "get" : { - "tags" : [ "Settings" ], - "summary" : "Returns values (content) of specified setting by its id and revision", "operationId" : "readSetting_1", "parameters" : [ { - "name" : "feature", "in" : "path", + "name" : "feature", "required" : true, "schema" : { "type" : "string" } }, { - "name" : "name", "in" : "path", + "name" : "name", "required" : true, "schema" : { "type" : "string" } }, { - "name" : "revision", "in" : "query", + "name" : "revision", "schema" : { "type" : "string" } } ], "responses" : { "default" : { - "description" : "Setting content", "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/SettingsModel" } } - } + }, + "description" : "Setting content" } - } + }, + "summary" : "Returns values (content) of specified setting by its id and revision", + "tags" : [ "Settings" ] }, "put" : { - "tags" : [ "Settings" ], - "summary" : "Creates or updates named setting. Creation scenario will use default setting value if no body specified in the request.", "operationId" : "saveSetting_1", "parameters" : [ { - "name" : "feature", "in" : "path", + "name" : "feature", "required" : true, "schema" : { "type" : "string" } }, { - "name" : "name", "in" : "path", + "name" : "name", "required" : true, "schema" : { "type" : "string" @@ -361,17 +334,24 @@ "204" : { "description" : "Setting created/updated successfully" } - } + }, + "summary" : "Creates or updates named setting. Creation scenario will use default setting value if no body specified in the request.", + "tags" : [ "Settings" ] } }, - "/api/settings/{feature}/names" : { + "/api/settings/{feature}/names/{name}/revisions" : { "get" : { - "tags" : [ "Settings" ], - "summary" : "Returns names of specified setting", - "operationId" : "readSettingNames_1", + "operationId" : "readRevisionsList_1", "parameters" : [ { + "in" : "path", "name" : "feature", + "required" : true, + "schema" : { + "type" : "string" + } + }, { "in" : "path", + "name" : "name", "required" : true, "schema" : { "type" : "string" @@ -379,102 +359,119 @@ } ], "responses" : { "default" : { - "description" : "List of setting names", "content" : { "application/json" : { "schema" : { - "$ref" : "#/components/schemas/SettingName" + "$ref" : "#/components/schemas/Revision" } } - } + }, + "description" : "List of revisions" } - } + }, + "summary" : "Returns revisions history of specified setting with specified id", + "tags" : [ "Settings" ] + } + }, + "/api/version" : { + "get" : { + "operationId" : "getVersion", + "responses" : { + "default" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Version" + } + } + }, + "description" : "Version information" + } + }, + "summary" : "Returns version of Polarion's extension", + "tags" : [ "Extension Information" ] } } }, "components" : { "schemas" : { - "ImportResult" : { + "Context" : { "type" : "object", + "description" : "Represents the context for building URLs related to Polarion services", "properties" : { - "updatedIds" : { - "type" : "array", - "description" : "List of IDs that were updated during the import process", - "items" : { - "type" : "string", - "description" : "List of IDs that were updated during the import process" - } + "baseUrl" : { + "type" : "string", + "description" : "Returns the base URL constructed with the extension context", + "example" : "/polarion/pdf-exporter" }, - "createdIds" : { - "type" : "array", - "description" : "List of IDs that were created during the import process", - "items" : { - "type" : "string", - "description" : "List of IDs that were created during the import process" - } + "extensionContext" : { + "type" : "string", + "description" : "The extension context used as a base for URL construction", + "example" : "pdf-exporter" }, - "unchangedIds" : { - "type" : "array", - "description" : "List of IDs that were unchanged during the import process", - "items" : { - "type" : "string", - "description" : "List of IDs that were unchanged during the import process" - } + "restUrl" : { + "type" : "string", + "description" : "Returns the REST API URL constructed with the extension context", + "example" : "/polarion/pdf-exporter/rest" + }, + "swaggerUiUrl" : { + "type" : "string", + "description" : "Returns the Swagger UI URL for the REST API" } - }, - "description" : "Represents the result of an Excel import operation" + } }, "FieldMetadata" : { "type" : "object", "properties" : { + "custom" : { + "type" : "boolean" + }, "id" : { "type" : "string" }, "label" : { "type" : "string" }, - "type" : { - "$ref" : "#/components/schemas/IType" - }, - "custom" : { - "type" : "boolean" - }, - "required" : { - "type" : "boolean" - }, "multi" : { "type" : "boolean" }, "options" : { - "uniqueItems" : true, "type" : "array", "items" : { "$ref" : "#/components/schemas/Option" - } + }, + "uniqueItems" : true + }, + "required" : { + "type" : "boolean" + }, + "type" : { + "$ref" : "#/components/schemas/IType" } } }, "IType" : { "type" : "object" }, - "Option" : { + "ITypeOpt" : { "type" : "object", "properties" : { - "key" : { + "default" : { + "type" : "boolean" + }, + "enumId" : { "type" : "string" }, - "name" : { + "hidden" : { + "type" : "boolean" + }, + "id" : { "type" : "string" - } - } - }, - "ITypeOpt" : { - "type" : "object", - "properties" : { + }, "name" : { "type" : "string" }, - "hidden" : { + "phantom" : { "type" : "boolean" }, "properties" : { @@ -483,129 +480,133 @@ "type" : "string" } }, - "id" : { - "type" : "string" - }, - "default" : { - "type" : "boolean" - }, "sequenceNumber" : { "type" : "integer", "format" : "int32" - }, - "phantom" : { - "type" : "boolean" - }, - "enumId" : { - "type" : "string" } } }, - "Context" : { + "ImportResult" : { "type" : "object", + "description" : "Represents the result of an Excel import operation", "properties" : { - "extensionContext" : { - "type" : "string", - "description" : "The extension context used as a base for URL construction.", - "example" : "pdf-exporter" + "createdIds" : { + "type" : "array", + "description" : "List of IDs that were created during the import process", + "items" : { + "type" : "string", + "description" : "List of IDs that were created during the import process" + } }, - "swaggerUiUrl" : { - "type" : "string", - "description" : "Returns the Swagger UI URL for the REST API." + "unchangedIds" : { + "type" : "array", + "description" : "List of IDs that were unchanged during the import process", + "items" : { + "type" : "string", + "description" : "List of IDs that were unchanged during the import process" + } }, - "restUrl" : { - "type" : "string", - "description" : "Returns the REST API URL constructed with the extension context.", - "example" : "/polarion/pdf-exporter/rest" + "updatedIds" : { + "type" : "array", + "description" : "List of IDs that were updated during the import process", + "items" : { + "type" : "string", + "description" : "List of IDs that were updated during the import process" + } + } + } + }, + "Option" : { + "type" : "object", + "properties" : { + "key" : { + "type" : "string" }, - "baseUrl" : { - "type" : "string", - "description" : "Returns the base URL constructed with the extension context.", - "example" : "/polarion/pdf-exporter" + "name" : { + "type" : "string" } - }, - "description" : "Represents the context for building URLs related to Polarion services." + } }, - "Version" : { + "Revision" : { "type" : "object", + "description" : "Revision details", "properties" : { - "bundleName" : { + "author" : { "type" : "string", - "description" : "The name of the bundle" + "description" : "The author of the revision" }, - "bundleVendor" : { + "baseline" : { "type" : "string", - "description" : "The vendor of the bundle" + "description" : "The baseline of the revision" }, - "supportEmail" : { + "date" : { "type" : "string", - "description" : "Support email for the bundle" + "description" : "The date of the revision" }, - "automaticModuleName" : { + "description" : { "type" : "string", - "description" : "The automatic module name" + "description" : "The description of the revision" }, - "bundleVersion" : { + "name" : { "type" : "string", - "description" : "The version of the bundle" - }, - "bundleBuildTimestamp" : { + "description" : "The name of the revision" + } + } + }, + "SettingName" : { + "type" : "object", + "properties" : { + "name" : { "type" : "string", - "description" : "The build timestamp of the bundle" + "description" : "The name of the setting" }, - "projectURL" : { + "scope" : { "type" : "string", - "description" : "The project URL" + "description" : "The scope of the setting" } - }, - "description" : "Details about the software version" + } }, "SettingsModel" : { "type" : "object", + "description" : "Settings model", "properties" : { "bundleTimestamp" : { "type" : "string", "description" : "The bundle timestamp of the setting" } - }, - "description" : "Settings model" + } }, - "Revision" : { + "Version" : { "type" : "object", + "description" : "Details about the software version", "properties" : { - "name" : { + "automaticModuleName" : { "type" : "string", - "description" : "The name of the revision" + "description" : "The automatic module name" }, - "date" : { + "bundleBuildTimestamp" : { "type" : "string", - "description" : "The date of the revision" + "description" : "The build timestamp of the bundle" }, - "author" : { + "bundleName" : { "type" : "string", - "description" : "The author of the revision" + "description" : "The name of the bundle" }, - "baseline" : { + "bundleVendor" : { "type" : "string", - "description" : "The baseline of the revision" + "description" : "The vendor of the bundle" }, - "description" : { + "bundleVersion" : { "type" : "string", - "description" : "The description of the revision" - } - }, - "description" : "Revision details" - }, - "SettingName" : { - "type" : "object", - "properties" : { - "name" : { + "description" : "The version of the bundle" + }, + "projectURL" : { "type" : "string", - "description" : "The name of the setting" + "description" : "The project URL" }, - "scope" : { + "supportEmail" : { "type" : "string", - "description" : "The scope of the setting" + "description" : "Support email for the bundle" } } } diff --git a/src/main/java/ch/sbb/polarion/extension/excel_importer/rest/controller/OpenAPIInfo.java b/src/main/java/ch/sbb/polarion/extension/excel_importer/rest/controller/OpenAPIInfo.java new file mode 100644 index 0000000..2b15c70 --- /dev/null +++ b/src/main/java/ch/sbb/polarion/extension/excel_importer/rest/controller/OpenAPIInfo.java @@ -0,0 +1,17 @@ +package ch.sbb.polarion.extension.excel_importer.rest.controller; + +import io.swagger.v3.oas.annotations.OpenAPIDefinition; +import io.swagger.v3.oas.annotations.info.Contact; +import io.swagger.v3.oas.annotations.info.Info; +import io.swagger.v3.oas.annotations.info.License; + +@OpenAPIDefinition( + info = @Info( + title = "Excel Importer REST API", + version = "v1", + description = "", + termsOfService = "", + contact = @Contact(name = "", url = ""), + license = @License(name = "", url = ""))) +public class OpenAPIInfo { +}