From 9a89ff6e9c5403045bf3926696965abd39272364 Mon Sep 17 00:00:00 2001 From: pbezliapovich Date: Mon, 2 Sep 2024 15:35:37 +0200 Subject: [PATCH] feat: Extended REST API annotation (#182) Refs: #180 Co-authored-by: Sergey Grigoriev --- docs/openapi.json | 2957 ++++++++--------- .../ConfigurationInternalController.java | 67 +- .../ConverterInternalController.java | 74 +- .../SettingsInternalController.java | 47 +- .../UtilityResourcesInternalController.java | 44 +- .../rest/model/ExportMetaInfoCallback.java | 6 + .../exporter/rest/model/NestedListsCheck.java | 3 + .../rest/model/WidthValidationResult.java | 12 + .../exporter/rest/model/WorkItemRefData.java | 11 +- .../rest/model/conversion/DocumentType.java | 7 + .../rest/model/conversion/ExportParams.java | 54 +- .../rest/model/conversion/Orientation.java | 13 +- .../rest/model/conversion/PaperSize.java | 20 +- .../rest/model/jobs/ConverterJobDetails.java | 9 + .../rest/model/jobs/ConverterJobStatus.java | 13 +- 15 files changed, 1728 insertions(+), 1609 deletions(-) diff --git a/docs/openapi.json b/docs/openapi.json index 03f9a06..dbc0438 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -1,1795 +1,1668 @@ { - "openapi": "3.0.1", - "info": { - "title": "PDF Exporter REST API", - "version": "v1" + "openapi" : "3.0.1", + "info" : { + "title" : "PDF Exporter REST API", + "version" : "v1" }, - "paths": { - "/api/checknestedlists": { - "post": { - "operationId": "checkNestedLists", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExportParams" + "tags" : [ { + "name" : "Settings", + "description" : "Operations related to PDF-exporter settings management" + } ], + "paths" : { + "/api/context" : { + "get" : { + "tags" : [ "Extension Information" ], + "summary" : "Returns basic context information of Polarion's extension", + "operationId" : "getContext", + "responses" : { + "default" : { + "description" : "default response", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Context" + } } } } - }, - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/NestedListsCheck" + } + } + }, + "/api/version" : { + "get" : { + "tags" : [ "Extension Information" ], + "summary" : "Returns version of Polarion's extension", + "operationId" : "getVersion", + "responses" : { + "default" : { + "description" : "default response", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/Version" } } - }, - "description": "default response" + } } - }, - "summary": "Checks whether document contains nested lists", - "tags": [ - "PDF Processing" - ] + } } }, - "/api/configuration/cors-config": { - "get": { - "operationId": "checkCORSConfig", - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConfigurationStatus" - } + "/api/settings/{feature}/names/{name}" : { + "post" : { + "tags" : [ "Settings" ], + "summary" : "Updates name of specified named setting", + "operationId" : "renameSetting_1", + "parameters" : [ { + "name" : "feature", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "name" : "name", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + } ], + "requestBody" : { + "content" : { + "application/json" : { + "schema" : { + "type" : "string" } - }, - "description": "default response" + } } }, - "summary": "Checks CORS configuration" - } - }, - "/api/configuration/default-settings": { - "get": { - "operationId": "checkDefaultSettings", - "parameters": [ - { - "in": "query", - "name": "scope", - "schema": { - "default": "", - "type": "string" + "responses" : { + "default" : { + "description" : "default response", + "content" : { + "*/*" : { } } } - ], - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConfigurationStatus" - } - } - }, - "description": "default response" + } + }, + "delete" : { + "tags" : [ "Settings" ], + "summary" : "Deletes specified setting by id", + "operationId" : "deleteSetting_1", + "parameters" : [ { + "name" : "feature", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "name" : "name", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "default" : { + "description" : "default response", + "content" : { + "application/json" : { } + } } - }, - "summary": "Checks default settings configuration" + } } }, - "/api/configuration/dle-toolbar-config": { - "get": { - "operationId": "checkDleToolbarConfig", - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConfigurationStatus" + "/api/settings/{feature}/default-content" : { + "get" : { + "tags" : [ "Settings" ], + "summary" : "Returns default values of specified setting", + "operationId" : "getDefaultValues_1", + "parameters" : [ { + "name" : "feature", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "default" : { + "description" : "default response", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/SettingsModel" } } - }, - "description": "default response" - } - }, - "summary": "Checks DLE Toolbar configuration" - } - }, - "/api/configuration/document-properties-pane-config": { - "get": { - "operationId": "checkDocumentPropertiesPaneConfig", - "parameters": [ - { - "in": "query", - "name": "scope", - "schema": { - "default": "", - "type": "string" } } - ], - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConfigurationStatus" - } - } - }, - "description": "default response" - } - }, - "summary": "Checks document properties pane configuration" + } } }, - "/api/configuration/live-report-config": { - "get": { - "operationId": "checkLiveReportConfig", - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ConfigurationStatus" + "/api/settings" : { + "get" : { + "tags" : [ "Settings" ], + "summary" : "Returns the complete list of all supported features", + "operationId" : "readFeaturesList_1", + "responses" : { + "default" : { + "description" : "default response", + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "type" : "string" + } } } - }, - "description": "default response" + } } - }, - "summary": "Checks Live Report configuration" + } } }, - "/api/configuration/weasyprint": { - "get": { - "operationId": "checkWeasyPrint", - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "items": { - "$ref": "#/components/schemas/ConfigurationStatus" - }, - "type": "array" + "/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", + "required" : true, + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "default" : { + "description" : "default response", + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/Revision" + } } } - }, - "description": "default response" + } } - }, - "summary": "Checks WeasyPrint configuration" + } } }, - "/api/context": { - "get": { - "operationId": "getContext", - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Context" + "/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", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "name" : "name", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "name" : "revision", + "in" : "query", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "default" : { + "description" : "default response", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/SettingsModel" } } - }, - "description": "default response" + } } - }, - "summary": "Returns basic context information of Polarion's extension", - "tags": [ - "Extension Information" - ] - } - }, - "/api/convert": { - "post": { - "operationId": "convertToPdf", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExportParams" + } + }, + "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", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "name" : "name", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + } ], + "requestBody" : { + "content" : { + "application/json" : { + "schema" : { + "type" : "string" } } } }, - "responses": { - "200": { - "content": { - "application/pdf": {} - }, - "description": "Content of PDF document as a byte array" + "responses" : { + "default" : { + "description" : "default response", + "content" : { + "*/*" : { } + } } - }, - "summary": "Returns requested Polarion's document converted to PDF", - "tags": [ - "PDF Processing" - ] + } } }, - "/api/convert/html": { - "post": { - "operationId": "convertHtmlToPdf", - "parameters": [ - { - "description": "default value: portrait", - "in": "query", - "name": "orientation", - "schema": { - "enum": [ - "PORTRAIT", - "LANDSCAPE" - ], - "type": "string" - } - }, - { - "description": "default value: A4", - "in": "query", - "name": "paperSize", - "schema": { - "enum": [ - "A5", - "A4", - "A3", - "B5", - "B4", - "JIS_B5", - "JIS_B4", - "LETTER", - "LEGAL", - "LEDGER" - ], - "type": "string" - } - }, - { - "description": "default value: document.pdf", - "in": "query", - "name": "fileName", - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "content": { - "text/html": { - "schema": { - "type": "string" + "/api/settings/{feature}/names" : { + "get" : { + "tags" : [ "Settings" ], + "summary" : "Returns names of specified setting", + "operationId" : "readSettingNames_1", + "parameters" : [ { + "name" : "feature", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "default" : { + "description" : "default response", + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/SettingName" + } + } } } - }, - "description": "input html (must include html and body elements)" - }, - "responses": { - "200": { - "content": { - "application/pdf": {} - }, - "description": "Content of PDF document as a byte array" } - }, - "summary": "Converts input HTML to PDF", - "tags": [ - "PDF Processing" - ] + } } }, - "/api/convert/jobs": { - "get": { - "operationId": "getAllPdfConverterJobs", - "responses": { - "200": { - "content": { - "application/json": {} - }, - "description": "Conversion jobs statuses" - } - }, - "summary": "Returns all active PDF conversion jobs statuses", - "tags": [ - "PDF Processing" - ] - }, - "post": { - "operationId": "startPdfConverterJob", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExportParams" + "/api/configuration/cors-config" : { + "get" : { + "summary" : "Checks CORS configuration", + "description" : "Retrieves the status of the CORS configuration.", + "operationId" : "checkCORSConfig", + "responses" : { + "200" : { + "description" : "Successfully retrieved CORS configuration", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConfigurationStatus" + } } } } - }, - "responses": { - "202": { - "description": "Conversion process is started, job URI is returned in Location header" - } - }, - "summary": "Starts asynchronous conversion job of Polarion's document to PDF", - "tags": [ - "PDF Processing" - ] + } } }, - "/api/convert/jobs/{id}": { - "get": { - "operationId": "getPdfConverterJobStatus", - "parameters": [ - { - "in": "path", - "name": "id", - "required": true, - "schema": { - "type": "string" + "/api/configuration/default-settings" : { + "get" : { + "summary" : "Checks default settings configuration", + "operationId" : "checkDefaultSettings", + "parameters" : [ { + "name" : "scope", + "in" : "query", + "schema" : { + "type" : "string", + "default" : "" + } + } ], + "responses" : { + "200" : { + "description" : "Successfully retrieved default settings configuration", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConfigurationStatus" + } + } } } - ], - "responses": { - "202": { - "content": { - "application/*": {} - }, - "description": "Conversion job is still in progress" - }, - "303": { - "content": { - "application/*": {} - }, - "description": "Conversion job is finished successfully, Location header contains result URL" - }, - "404": { - "description": "Conversion job id is unknown" - }, - "409": { - "content": { - "application/json": {} - }, - "description": "Conversion job is failed or cancelled" - } - }, - "summary": "Returns PDF conversion job status", - "tags": [ - "PDF Processing" - ] + } } }, - "/api/convert/jobs/{id}/result": { - "get": { - "operationId": "getPdfConverterJobResult", - "parameters": [ - { - "in": "path", - "name": "id", - "required": true, - "schema": { - "type": "string" + "/api/configuration/dle-toolbar-config" : { + "get" : { + "summary" : "Checks DLE Toolbar configuration", + "operationId" : "checkDleToolbarConfig", + "responses" : { + "200" : { + "description" : "Successfully retrieved DLE Toolbar configuration", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConfigurationStatus" + } + } } } - ], - "responses": { - "200": { - "content": { - "application/pdf": {} - }, - "description": "Conversion job result is ready" - }, - "204": { - "description": "Conversion job is still in progress" - }, - "404": { - "description": "Conversion job id is unknown" - }, - "409": { - "description": "Conversion job is failed, cancelled or result is unreachable" - } - }, - "summary": "Returns PDF conversion job result", - "tags": [ - "PDF Processing" - ] + } } }, - "/api/document-language": { - "get": { - "operationId": "getDocumentLanguage", - "parameters": [ - { - "in": "query", - "name": "projectId", - "schema": { - "type": "string" - } - }, - { - "in": "query", - "name": "spaceId", - "schema": { - "type": "string" - } - }, - { - "in": "query", - "name": "documentName", - "schema": { - "type": "string" - } - }, - { - "in": "query", - "name": "revision", - "schema": { - "type": "string" - } - } - ], - "responses": { - "default": { - "content": { - "text/plain": { - "schema": { - "type": "string" + "/api/configuration/document-properties-pane-config" : { + "get" : { + "summary" : "Checks document properties pane configuration", + "operationId" : "checkDocumentPropertiesPaneConfig", + "parameters" : [ { + "name" : "scope", + "in" : "query", + "schema" : { + "type" : "string", + "default" : "" + } + } ], + "responses" : { + "200" : { + "description" : "Successfully retrieved document properties pane configuration", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConfigurationStatus" } } - }, - "description": "default response" + } } - }, - "summary": "Gets language of specified Polarion's document, defined in its custom field 'docLanguage'", - "tags": [ - "Utility resources" - ] + } } }, - "/api/export-filename": { - "get": { - "operationId": "getFileName", - "parameters": [ - { - "in": "query", - "name": "locationPath", - "schema": { - "type": "string" - } - }, - { - "in": "query", - "name": "revision", - "schema": { - "type": "string" - } - }, - { - "in": "query", - "name": "documentType", - "schema": { - "enum": [ - "DOCUMENT", - "WIKI", - "REPORT" - ], - "type": "string" - } - }, - { - "in": "query", - "name": "scope", - "schema": { - "type": "string" - } - } - ], - "responses": { - "default": { - "content": { - "text/plain": { - "schema": { - "type": "string" + "/api/configuration/live-report-config" : { + "get" : { + "summary" : "Checks Live Report configuration", + "operationId" : "checkLiveReportConfig", + "responses" : { + "200" : { + "description" : "Successfully retrieved Live Report configuration", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ConfigurationStatus" } } - }, - "description": "default response" + } } - }, - "summary": "Gets a filename, prepared with velocity and placeholders", - "tags": [ - "Utility resources" - ] + } } }, - "/api/link-role-names": { - "get": { - "operationId": "readLinkRoleNames", - "parameters": [ - { - "description": "Project scope in form project//", - "in": "query", - "name": "scope", - "schema": { - "type": "string" - } - } - ], - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "items": { - "type": "string" - }, - "type": "array" + "/api/configuration/weasyprint" : { + "get" : { + "summary" : "Checks WeasyPrint configuration", + "description" : "Retrieves the status of the WeasyPrint configuration.", + "operationId" : "checkWeasyPrint", + "responses" : { + "200" : { + "description" : "Successfully retrieved WeasyPrint configuration", + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ConfigurationStatus" + } } } - }, - "description": "default response" + } } - }, - "summary": "Gets list of possible WorkItem link role names in specified project scope", - "tags": [ - "Utility resources" - ] + } } }, - "/api/prepared-html-content": { - "post": { - "operationId": "prepareHtmlContent", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExportParams" + "/api/checknestedlists" : { + "post" : { + "tags" : [ "PDF Processing" ], + "summary" : "Checks whether document contains nested lists", + "operationId" : "checkNestedLists", + "requestBody" : { + "description" : "Export parameters used to locate and check the document for nested lists", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ExportParams" } } - } - }, - "responses": { - "200": { - "content": { - "text/html": {} - }, - "description": "Prepared HTML content" - } + }, + "required" : true }, - "summary": "Returns prepared HTML which will be used for PDF conversion using WeasyPrint", - "tags": [ - "PDF Processing" - ] - } - }, - "/api/projects/{projectId}/name": { - "get": { - "operationId": "getProjectName", - "parameters": [ - { - "in": "path", - "name": "projectId", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "default": { - "content": { - "text/plain": { - "schema": { - "type": "string" + "responses" : { + "200" : { + "description" : "Check completed successfully, returning whether nested lists are present", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/NestedListsCheck" } } - }, - "description": "default response" + } } - }, - "summary": "Gets name of specified Polarion's project", - "tags": [ - "Utility resources" - ] + } } }, - "/api/settings": { - "get": { - "operationId": "readFeaturesList_1", - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "items": { - "type": "string" - }, - "type": "array" - } + "/api/convert/html" : { + "post" : { + "tags" : [ "PDF Processing" ], + "summary" : "Converts input HTML to PDF", + "operationId" : "convertHtmlToPdf", + "parameters" : [ { + "name" : "orientation", + "in" : "query", + "description" : "default value: portrait", + "schema" : { + "type" : "string", + "description" : "Orientation of the output document", + "enum" : [ "PORTRAIT", "LANDSCAPE" ] + } + }, { + "name" : "paperSize", + "in" : "query", + "description" : "default value: A4", + "schema" : { + "type" : "string", + "description" : "Standard paper sizes", + "enum" : [ "A5", "A4", "A3", "B5", "B4", "JIS_B5", "JIS_B4", "LETTER", "LEGAL", "LEDGER" ] + } + }, { + "name" : "fileName", + "in" : "query", + "description" : "default value: document.pdf", + "schema" : { + "type" : "string" + } + } ], + "requestBody" : { + "description" : "input html (must include html and body elements)", + "content" : { + "text/html" : { + "schema" : { + "type" : "string" } - }, - "description": "default response" + } } }, - "summary": "Returns the complete list of all supported features", - "tags": [ - "Settings" - ] + "responses" : { + "200" : { + "description" : "Content of PDF document as a byte array", + "content" : { + "application/pdf" : { } + } + } + } } }, - "/api/settings/cover-page/names/{name}/images": { - "delete": { - "operationId": "deleteImages", - "parameters": [ - { - "in": "path", - "name": "name", - "required": true, - "schema": { - "type": "string" + "/api/convert" : { + "post" : { + "tags" : [ "PDF Processing" ], + "summary" : "Returns requested Polarion's document converted to PDF", + "operationId" : "convertToPdf", + "requestBody" : { + "description" : "Export parameters to generate the PDF", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ExportParams" + } } }, - { - "in": "query", - "name": "scope", - "schema": { - "default": "", - "type": "string" + "required" : true + }, + "responses" : { + "200" : { + "description" : "Content of PDF document as a byte array", + "content" : { + "application/pdf" : { } } } - ], - "responses": { - "default": { - "content": { - "application/json": {} - }, - "description": "default response" - } - }, - "summary": "Deletes images in SVN linked to specified cover page within specified scope (global or certain project)", - "tags": [ - "Settings" - ] + } } }, - "/api/settings/cover-page/templates": { - "get": { - "operationId": "getCoverPageTemplateNames", - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "items": { - "type": "string" - }, - "type": "array" + "/api/convert/jobs" : { + "get" : { + "tags" : [ "PDF Processing" ], + "summary" : "Returns all active PDF conversion jobs statuses", + "operationId" : "getAllPdfConverterJobs", + "responses" : { + "200" : { + "description" : "Conversion jobs statuses", + "content" : { + "application/json" : { + "schema" : { + "type" : "string" } } - }, - "description": "default response" + } } + } + }, + "post" : { + "tags" : [ "PDF Processing" ], + "summary" : "Starts asynchronous conversion job of Polarion's document to PDF", + "operationId" : "startPdfConverterJob", + "requestBody" : { + "description" : "Export parameters to generate the PDF", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ExportParams" + } + } + }, + "required" : true }, - "summary": "Get list of cover page predefined template names", - "tags": [ - "Settings" - ] + "responses" : { + "202" : { + "description" : "Conversion process is started, job URI is returned in Location header" + } + } } }, - "/api/settings/cover-page/templates/{template}": { - "post": { - "operationId": "persistCoverPageTemplate", - "parameters": [ - { - "in": "path", - "name": "template", - "required": true, - "schema": { - "type": "string" + "/api/convert/jobs/{id}/result" : { + "get" : { + "tags" : [ "PDF Processing" ], + "summary" : "Returns PDF conversion job result", + "operationId" : "getPdfConverterJobResult", + "parameters" : [ { + "name" : "id", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "Conversion job result is ready", + "content" : { + "application/pdf" : { } } }, - { - "in": "query", - "name": "scope", - "schema": { - "type": "string" - } - } - ], - "responses": { - "default": { - "content": { - "*/*": {} - }, - "description": "default response" + "204" : { + "description" : "Conversion job is still in progress" + }, + "409" : { + "description" : "Conversion job is failed, cancelled or result is unreachable" + }, + "404" : { + "description" : "Conversion job id is unknown" } - }, - "summary": "Persist content of cover page predefined template", - "tags": [ - "Settings" - ] + } } }, - "/api/settings/localization/names/{name}/download": { - "get": { - "operationId": "downloadTranslations", - "parameters": [ - { - "in": "path", - "name": "name", - "required": true, - "schema": { - "type": "string" + "/api/convert/jobs/{id}" : { + "get" : { + "tags" : [ "PDF Processing" ], + "summary" : "Returns PDF conversion job status", + "operationId" : "getPdfConverterJobStatus", + "parameters" : [ { + "name" : "id", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "303" : { + "description" : "Conversion job is finished successfully, Location header contains result URL", + "content" : { + "application/*" : { + "schema" : { + "$ref" : "#/components/schemas/ConverterJobDetails" + } + } } }, - { - "in": "query", - "name": "language", - "schema": { - "type": "string" + "202" : { + "description" : "Conversion job is still in progress", + "content" : { + "application/*" : { + "schema" : { + "$ref" : "#/components/schemas/ConverterJobDetails" + } + } } }, - { - "in": "query", - "name": "revision", - "schema": { - "type": "string" - } + "409" : { + "description" : "Conversion job is failed or cancelled" }, - { - "in": "query", - "name": "scope", - "schema": { - "type": "string" - } - } - ], - "responses": { - "default": { - "content": { - "application/xml": {} - }, - "description": "default response" + "404" : { + "description" : "Conversion job id is unknown" } - }, - "summary": "Downloads localization values by name of localization settings", - "tags": [ - "Settings" - ] + } } }, - "/api/settings/localization/upload": { - "post": { - "operationId": "uploadTranslations", - "parameters": [ - { - "in": "query", - "name": "language", - "schema": { - "type": "string" + "/api/prepared-html-content" : { + "post" : { + "tags" : [ "PDF Processing" ], + "summary" : "Returns prepared HTML which will be used for PDF conversion using WeasyPrint", + "operationId" : "prepareHtmlContent", + "requestBody" : { + "description" : "Export parameters to generate the PDF", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ExportParams" + } } }, - { - "in": "query", - "name": "scope", - "schema": { - "type": "string" + "required" : true + }, + "responses" : { + "200" : { + "description" : "Prepared HTML content", + "content" : { + "text/html" : { } } } - ], - "requestBody": { - "content": { - "multipart/form-data": { - "schema": { - "properties": { - "file": { - "$ref": "#/components/schemas/FormDataBodyPart" - } - }, - "type": "object" + } + } + }, + "/api/validate" : { + "post" : { + "tags" : [ "PDF Processing" ], + "summary" : "Validates if requested Polarion's document been converted to PDF doesn't contain pages which content exceeds page's width", + "operationId" : "validatePdfWidth", + "parameters" : [ { + "name" : "max-results", + "in" : "query", + "description" : "Limit of 'invalid' pages in response", + "required" : true, + "schema" : { + "type" : "integer", + "format" : "int32" + } + } ], + "requestBody" : { + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/ExportParams" } } } }, - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "additionalProperties": { - "type": "string" - }, - "type": "object" + "responses" : { + "200" : { + "description" : "Validation result", + "content" : { + "application/json" : { + "schema" : { + "$ref" : "#/components/schemas/WidthValidationResult" } } - }, - "description": "default response" + } } - }, - "summary": "Uploads localization values", - "tags": [ - "Settings" - ] + } } }, - "/api/settings/style-package/suitable-names": { - "get": { - "operationId": "getSuitableStylePackageNames", - "parameters": [ - { - "in": "query", - "name": "projectId", - "schema": { - "type": "string" - } - }, - { - "in": "query", - "name": "spaceId", - "schema": { - "type": "string" - } - }, - { - "in": "query", - "name": "documentName", - "schema": { - "type": "string" - } - } - ], - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "items": { - "$ref": "#/components/schemas/SettingName" - }, - "type": "array" - } - } - }, - "description": "default response" + "/api/settings/cover-page/names/{name}/images" : { + "delete" : { + "tags" : [ "Settings" ], + "summary" : "Deletes images in SVN linked to specified cover page within specified scope (global or certain project)", + "operationId" : "deleteImages", + "parameters" : [ { + "name" : "name", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "name" : "scope", + "in" : "query", + "schema" : { + "type" : "string", + "default" : "" + } + } ], + "responses" : { + "200" : { + "description" : "Images deleted successfully" } }, - "summary": "Get list of style packages suitable for a document", - "tags": [ - "Settings" - ] + "security" : [ { + "bearerAuth" : [ ] + } ] } }, - "/api/settings/{feature}/default-content": { - "get": { - "operationId": "getDefaultValues_1", - "parameters": [ - { - "in": "path", - "name": "feature", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SettingsModel" - } - } - }, - "description": "default response" + "/api/settings/localization/names/{name}/download" : { + "get" : { + "tags" : [ "Settings" ], + "summary" : "Downloads localization values by name of localization settings", + "operationId" : "downloadTranslations", + "parameters" : [ { + "name" : "name", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "name" : "language", + "in" : "query", + "schema" : { + "type" : "string" + } + }, { + "name" : "revision", + "in" : "query", + "schema" : { + "type" : "string" + } + }, { + "name" : "scope", + "in" : "query", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "Localization file downloaded successfully" } }, - "summary": "Returns default values of specified setting", - "tags": [ - "Settings" - ] + "security" : [ { + "bearerAuth" : [ ] + } ] } }, - "/api/settings/{feature}/names": { - "get": { - "operationId": "readSettingNames_1", - "parameters": [ - { - "in": "path", - "name": "feature", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "items": { - "$ref": "#/components/schemas/SettingName" - }, - "type": "array" - } - } - }, - "description": "default response" + "/api/settings/cover-page/templates" : { + "get" : { + "tags" : [ "Settings" ], + "summary" : "Get list of cover page predefined template names", + "operationId" : "getCoverPageTemplateNames", + "responses" : { + "200" : { + "description" : "Template names retrieved successfully" } }, - "summary": "Returns names of specified setting", - "tags": [ - "Settings" - ] + "security" : [ { + "bearerAuth" : [ ] + } ] } }, - "/api/settings/{feature}/names/{name}": { - "delete": { - "operationId": "deleteSetting_1", - "parameters": [ - { - "in": "path", - "name": "feature", - "required": true, - "schema": { - "type": "string" - } - }, - { - "in": "path", - "name": "name", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "default": { - "content": { - "application/json": {} - }, - "description": "default response" - } - }, - "summary": "Deletes specified setting by id", - "tags": [ - "Settings" - ] - }, - "post": { - "operationId": "renameSetting_1", - "parameters": [ - { - "in": "path", - "name": "feature", - "required": true, - "schema": { - "type": "string" - } - }, - { - "in": "path", - "name": "name", - "required": true, - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "string" - } - } + "/api/settings/style-package/suitable-names" : { + "get" : { + "tags" : [ "Settings" ], + "summary" : "Get list of style packages suitable for a document", + "operationId" : "getSuitableStylePackageNames", + "parameters" : [ { + "name" : "projectId", + "in" : "query", + "schema" : { + "type" : "string" + } + }, { + "name" : "spaceId", + "in" : "query", + "schema" : { + "type" : "string" + } + }, { + "name" : "documentName", + "in" : "query", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "Successfully retrieved the list of style package names" } }, - "responses": { - "default": { - "content": { - "*/*": {} - }, - "description": "default response" + "security" : [ { + "bearerAuth" : [ ] + } ] + } + }, + "/api/settings/cover-page/templates/{template}" : { + "post" : { + "tags" : [ "Settings" ], + "summary" : "Persist content of cover page predefined template", + "operationId" : "persistCoverPageTemplate", + "parameters" : [ { + "name" : "template", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + }, { + "name" : "scope", + "in" : "query", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "Template persisted successfully" } }, - "summary": "Updates name of specified named setting", - "tags": [ - "Settings" - ] + "security" : [ { + "bearerAuth" : [ ] + } ] } }, - "/api/settings/{feature}/names/{name}/content": { - "get": { - "operationId": "readSetting_1", - "parameters": [ - { - "in": "path", - "name": "feature", - "required": true, - "schema": { - "type": "string" - } - }, - { - "in": "path", - "name": "name", - "required": true, - "schema": { - "type": "string" - } - }, - { - "in": "query", - "name": "revision", - "schema": { - "type": "string" - } - } - ], - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SettingsModel" + "/api/settings/localization/upload" : { + "post" : { + "tags" : [ "Settings" ], + "summary" : "Uploads localization values", + "operationId" : "uploadTranslations", + "parameters" : [ { + "name" : "language", + "in" : "query", + "schema" : { + "type" : "string" + } + }, { + "name" : "scope", + "in" : "query", + "schema" : { + "type" : "string" + } + } ], + "requestBody" : { + "content" : { + "multipart/form-data" : { + "schema" : { + "type" : "object", + "properties" : { + "file" : { + "$ref" : "#/components/schemas/FormDataBodyPart" + } } } - }, - "description": "default response" - } - }, - "summary": "Returns values (content) of specified setting by its id and revision", - "tags": [ - "Settings" - ] - }, - "put": { - "operationId": "saveSetting_1", - "parameters": [ - { - "in": "path", - "name": "feature", - "required": true, - "schema": { - "type": "string" - } - }, - { - "in": "path", - "name": "name", - "required": true, - "schema": { - "type": "string" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "type": "string" - } } } }, - "responses": { - "default": { - "content": { - "*/*": {} - }, - "description": "default response" + "responses" : { + "200" : { + "description" : "Localization file uploaded successfully" } }, - "summary": "Creates or updates named setting. Creation scenario will use default setting value if no body specified in the request.", - "tags": [ - "Settings" - ] + "security" : [ { + "bearerAuth" : [ ] + } ] } }, - "/api/settings/{feature}/names/{name}/revisions": { - "get": { - "operationId": "readRevisionsList_1", - "parameters": [ - { - "in": "path", - "name": "feature", - "required": true, - "schema": { - "type": "string" - } - }, - { - "in": "path", - "name": "name", - "required": true, - "schema": { - "type": "string" - } - } - ], - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "items": { - "$ref": "#/components/schemas/Revision" - }, - "type": "array" - } - } - }, - "description": "default response" - } - }, - "summary": "Returns revisions history of specified setting with specified id", - "tags": [ - "Settings" - ] + "/api/document-language" : { + "get" : { + "tags" : [ "Utility resources" ], + "summary" : "Gets language of specified Polarion's document, defined in its custom field 'docLanguage'", + "operationId" : "getDocumentLanguage", + "parameters" : [ { + "name" : "projectId", + "in" : "query", + "schema" : { + "type" : "string" + } + }, { + "name" : "spaceId", + "in" : "query", + "schema" : { + "type" : "string" + } + }, { + "name" : "documentName", + "in" : "query", + "schema" : { + "type" : "string" + } + }, { + "name" : "revision", + "in" : "query", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "Successfully retrieved document language" + } + } } }, - "/api/validate": { - "post": { - "operationId": "validatePdfWidth", - "parameters": [ - { - "description": "Limit of 'invalid' pages in response", - "in": "query", - "name": "max-results", - "required": true, - "schema": { - "format": "int32", - "type": "integer" - } - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExportParams" - } - } - } - }, - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/WidthValidationResult" - } - } - }, - "description": "default response" - } - }, - "summary": "Validates if requested Polarion's document been converted to PDF doesn't contain pages which content exceeds page's width", - "tags": [ - "PDF Processing" - ] + "/api/export-filename" : { + "get" : { + "tags" : [ "Utility resources" ], + "summary" : "Gets a filename, prepared with velocity and placeholders", + "operationId" : "getFileName", + "parameters" : [ { + "name" : "locationPath", + "in" : "query", + "schema" : { + "type" : "string" + } + }, { + "name" : "revision", + "in" : "query", + "schema" : { + "type" : "string" + } + }, { + "name" : "documentType", + "in" : "query", + "schema" : { + "type" : "string", + "description" : "Type of the document", + "enum" : [ "DOCUMENT", "WIKI", "REPORT" ] + } + }, { + "name" : "scope", + "in" : "query", + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "Successfully generated filename" + } + } } }, - "/api/version": { - "get": { - "operationId": "getVersion", - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Version" - } - } - }, - "description": "default response" - } - }, - "summary": "Returns version of Polarion's extension", - "tags": [ - "Extension Information" - ] + "/api/projects/{projectId}/name" : { + "get" : { + "tags" : [ "Utility resources" ], + "summary" : "Gets name of specified Polarion's project", + "operationId" : "getProjectName", + "parameters" : [ { + "name" : "projectId", + "in" : "path", + "required" : true, + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "Successfully retrieved project name" + } + } + } + }, + "/api/webhooks/status" : { + "get" : { + "tags" : [ "Utility resources" ], + "summary" : "Gets webhooks status - if they are enabled or not", + "operationId" : "getWebhooksStatus", + "responses" : { + "200" : { + "description" : "Webhooks status" + } + } } }, - "/api/webhooks/status": { - "get": { - "operationId": "getWebhooksStatus", - "responses": { - "default": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/WebhooksStatus" + "/api/link-role-names" : { + "get" : { + "tags" : [ "Utility resources" ], + "summary" : "Gets list of possible WorkItem link role names in specified project scope", + "operationId" : "readLinkRoleNames", + "parameters" : [ { + "name" : "scope", + "in" : "query", + "description" : "Project scope in form project//", + "required" : true, + "schema" : { + "type" : "string" + } + } ], + "responses" : { + "200" : { + "description" : "Successfully retrieved list of link role names", + "content" : { + "application/json" : { + "schema" : { + "type" : "array", + "items" : { + "type" : "string" + } } } - }, - "description": "default response" + } } - }, - "summary": "Gets webhooks status - if they are enabled or not", - "tags": [ - "Utility resources" - ] + } } } }, - "components": { - "schemas": { - "BodyPart": { - "properties": { - "contentDisposition": { - "$ref": "#/components/schemas/ContentDisposition" - }, - "entity": { - "type": "object" - }, - "headers": { - "additionalProperties": { - "items": { - "type": "string" - }, - "type": "array" - }, - "type": "object" - }, - "mediaType": { - "properties": { - "parameters": { - "additionalProperties": { - "type": "string" - }, - "type": "object" - }, - "subtype": { - "type": "string" - }, - "type": { - "type": "string" - }, - "wildcardSubtype": { - "type": "boolean" - }, - "wildcardType": { - "type": "boolean" - } - }, - "type": "object" - }, - "messageBodyWorkers": { - "$ref": "#/components/schemas/MessageBodyWorkers" + "components" : { + "schemas" : { + "Context" : { + "type" : "object", + "properties" : { + "extensionContext" : { + "type" : "string" }, - "parameterizedHeaders": { - "additionalProperties": { - "items": { - "$ref": "#/components/schemas/ParameterizedHeader" - }, - "type": "array" - }, - "type": "object" + "swaggerUiUrl" : { + "type" : "string" }, - "parent": { - "$ref": "#/components/schemas/MultiPart" + "restUrl" : { + "type" : "string" }, - "providers": { - "type": "object" - } - }, - "type": "object" - }, - "ConfigurationStatus": { - "properties": { - "details": { - "type": "string" - }, - "name": { - "type": "string" - }, - "status": { - "enum": [ - "OK", - "WARNING", - "ERROR" - ], - "type": "string" + "baseUrl" : { + "type" : "string" } - }, - "type": "object" + } }, - "ContentDisposition": { - "properties": { - "creationDate": { - "format": "date-time", - "type": "string" - }, - "fileName": { - "type": "string" - }, - "modificationDate": { - "format": "date-time", - "type": "string" - }, - "parameters": { - "additionalProperties": { - "type": "string" - }, - "type": "object" + "Version" : { + "type" : "object", + "properties" : { + "bundleName" : { + "type" : "string" }, - "readDate": { - "format": "date-time", - "type": "string" + "bundleVendor" : { + "type" : "string" }, - "size": { - "format": "int64", - "type": "integer" + "supportEmail" : { + "type" : "string" }, - "type": { - "type": "string" - } - }, - "type": "object" - }, - "Context": { - "properties": { - "baseUrl": { - "type": "string" + "automaticModuleName" : { + "type" : "string" }, - "extensionContext": { - "type": "string" + "bundleVersion" : { + "type" : "string" }, - "restUrl": { - "type": "string" + "bundleBuildTimestamp" : { + "type" : "string" }, - "swaggerUiUrl": { - "type": "string" + "projectURL" : { + "type" : "string" + }, + "bundleBuildTimestampDigitsOnly" : { + "type" : "string" } - }, - "type": "object" + } }, - "ExportParams": { - "properties": { - "chapters": { - "items": { - "type": "string" - }, - "type": "array" - }, - "coverPage": { - "type": "string" + "SettingsModel" : { + "type" : "object", + "properties" : { + "bundleTimestamp" : { + "type" : "string" + } + } + }, + "Revision" : { + "type" : "object", + "properties" : { + "name" : { + "type" : "string" }, - "css": { - "type": "string" + "date" : { + "type" : "string" }, - "cutEmptyChapters": { - "type": "boolean" + "author" : { + "type" : "string" }, - "cutEmptyWIAttributes": { - "type": "boolean" + "baseline" : { + "type" : "string" }, - "cutLocalUrls": { - "type": "boolean" + "description" : { + "type" : "string" + } + } + }, + "SettingName" : { + "type" : "object", + "properties" : { + "name" : { + "type" : "string" }, - "documentType": { - "enum": [ - "DOCUMENT", - "WIKI", - "REPORT" - ], - "type": "string" + "scope" : { + "type" : "string" + } + } + }, + "ConfigurationStatus" : { + "type" : "object", + "properties" : { + "name" : { + "type" : "string" }, - "enableCommentsRendering": { - "type": "boolean" + "status" : { + "type" : "string", + "enum" : [ "OK", "WARNING", "ERROR" ] }, - "fitToPage": { - "type": "boolean" + "details" : { + "type" : "string" + } + } + }, + "NestedListsCheck" : { + "type" : "object", + "properties" : { + "containsNestedLists" : { + "type" : "boolean", + "description" : "Indicates whether the content contains nested lists" + } + }, + "description" : "Check result indicating whether nested lists are present" + }, + "ExportParams" : { + "required" : [ "Location path" ], + "type" : "object", + "properties" : { + "Project ID" : { + "type" : "string", + "description" : "The unique identifier for the project", + "example" : "elibrary" + }, + "Location path" : { + "type" : "string", + "description" : "Document path for export" + }, + "revision" : { + "type" : "string", + "description" : "The specific revision of the document to export" + }, + "documentType" : { + "type" : "string", + "description" : "Type of the document", + "example" : "DOCUMENT", + "enum" : [ "DOCUMENT", "WIKI", "REPORT" ] + }, + "coverPage" : { + "type" : "string", + "description" : "Cover page settings name" + }, + "css" : { + "type" : "string", + "description" : "CSS settings name" + }, + "headerFooter" : { + "type" : "string", + "description" : "Header Footer settings name" + }, + "localization" : { + "type" : "string", + "description" : "Localization settings name" + }, + "webhooks" : { + "type" : "string", + "description" : "Webhooks settings name" + }, + "headersColor" : { + "type" : "string", + "description" : "Color to be used for headers in the document. By default dark blue color (Polarion's default)" + }, + "orientation" : { + "type" : "string", + "description" : "Orientation of the output document", + "default" : "PORTRAIT", + "enum" : [ "PORTRAIT", "LANDSCAPE" ] + }, + "paperSize" : { + "type" : "string", + "description" : "Standard paper sizes", + "default" : "A4", + "enum" : [ "A5", "A4", "A3", "B5", "B4", "JIS_B5", "JIS_B4", "LETTER", "LEGAL", "LEDGER" ] + }, + "fitToPage" : { + "type" : "boolean", + "description" : "Content should be scaled to fit the page", + "default" : true + }, + "enableCommentsRendering" : { + "type" : "boolean", + "description" : "Comments should be rendered in the exported document", + "default" : true + }, + "watermark" : { + "type" : "boolean", + "description" : "Watermark content to be applied to the document" + }, + "markReferencedWorkitems" : { + "type" : "boolean", + "description" : "Referenced work items should be marked in the document" + }, + "cutEmptyChapters" : { + "type" : "boolean", + "description" : "Empty chapters should be removed from the document" + }, + "cutEmptyWIAttributes" : { + "type" : "boolean", + "description" : "Empty work item attributes should be removed from the document", + "default" : true + }, + "cutLocalUrls" : { + "type" : "boolean", + "description" : "Local Polarion URLs should be removed from the document" + }, + "followHTMLPresentationalHints" : { + "type" : "boolean", + "description" : "HTML presentational hints should be followed", + "default" : true + }, + "numberedListStyles" : { + "type" : "string", + "description" : "SCC styles to be applied to numbered lists in the document" + }, + "chapters" : { + "type" : "array", + "description" : "Specific higher level chapters", + "items" : { + "type" : "string", + "description" : "Specific higher level chapters" + } }, - "followHTMLPresentationalHints": { - "type": "boolean" + "language" : { + "type" : "string", + "description" : "Language in the exported document" + }, + "linkedWorkitemRoles" : { + "type" : "array", + "description" : "Specific Workitem roles", + "example" : [ "has parent", "depends on" ], + "items" : { + "type" : "string", + "description" : "Specific Workitem roles", + "example" : "[\"has parent\",\"depends on\"]" + } }, - "headerFooter": { - "type": "string" + "urlQueryParameters" : { + "type" : "object", + "additionalProperties" : { + "type" : "string", + "description" : "Map of attributes extracted from the URL" + }, + "description" : "Map of attributes extracted from the URL" }, - "headersColor": { - "type": "string" + "internalContent" : { + "type" : "string", + "description" : "Internal content" + } + } + }, + "ConverterJobDetails" : { + "type" : "object", + "properties" : { + "status" : { + "type" : "string", + "description" : "Status of the converter job", + "example" : "IN_PROGRESS", + "enum" : [ "IN_PROGRESS", "SUCCESSFULLY_FINISHED", "FAILED", "CANCELLED" ] + }, + "errorMessage" : { + "type" : "string", + "description" : "Error message if the conversion failed" + } + }, + "description" : "Details of the converter job including status and error message if any" + }, + "PageInfo" : { + "type" : "object", + "properties" : { + "number" : { + "type" : "integer", + "description" : "The number of the page that failed validation", + "format" : "int32" + }, + "content" : { + "type" : "string", + "description" : "The encoded content of the page that failed validation" + } + }, + "description" : "Information about a specific page that failed validation, including its number and content." + }, + "WidthValidationResult" : { + "type" : "object", + "properties" : { + "invalidPages" : { + "$ref" : "#/components/schemas/PageInfo" }, - "internalContent": { - "type": "string" + "suspiciousWorkItems" : { + "$ref" : "#/components/schemas/WorkItemRefData" + } + }, + "description" : "Result of the width validation process" + }, + "WorkItemRefData" : { + "type" : "object", + "properties" : { + "id" : { + "type" : "string", + "description" : "The unique identifier of the Work item" }, - "language": { - "type": "string" + "project" : { + "type" : "string", + "description" : "The unique identifier of the project to which the Work item belongs" }, - "linkedWorkitemRoles": { - "items": { - "type": "string" - }, - "type": "array" - }, - "localization": { - "type": "string" - }, - "locationPath": { - "type": "string" - }, - "markReferencedWorkitems": { - "type": "boolean" - }, - "numberedListStyles": { - "type": "string" - }, - "orientation": { - "enum": [ - "PORTRAIT", - "LANDSCAPE" - ], - "type": "string" - }, - "paperSize": { - "enum": [ - "A5", - "A4", - "A3", - "B5", - "B4", - "JIS_B5", - "JIS_B4", - "LETTER", - "LEGAL", - "LEDGER" - ], - "type": "string" - }, - "projectId": { - "type": "string" - }, - "revision": { - "type": "string" - }, - "urlQueryParameters": { - "additionalProperties": { - "type": "string" - }, - "type": "object" + "layout" : { + "type" : "string", + "description" : "Work item layout" }, - "watermark": { - "type": "boolean" + "revision" : { + "type" : "string", + "description" : "The revision number of the Work item" }, - "webhooks": { - "type": "string" + "link" : { + "type" : "string" } }, - "type": "object" + "description" : "Data class representing a reference to a work item, including ID, project, layout, and revision" }, - "FormDataBodyPart": { - "properties": { - "contentDisposition": { - "$ref": "#/components/schemas/ContentDisposition" - }, - "entity": { - "type": "object" - }, - "formDataContentDisposition": { - "$ref": "#/components/schemas/FormDataContentDisposition" + "BodyPart" : { + "type" : "object", + "properties" : { + "contentDisposition" : { + "$ref" : "#/components/schemas/ContentDisposition" + }, + "entity" : { + "type" : "object" + }, + "headers" : { + "type" : "object", + "additionalProperties" : { + "type" : "array", + "items" : { + "type" : "string" + } + } }, - "headers": { - "additionalProperties": { - "items": { - "type": "string" - }, - "type": "array" - }, - "type": "object" - }, - "mediaType": { - "properties": { - "parameters": { - "additionalProperties": { - "type": "string" - }, - "type": "object" + "mediaType" : { + "type" : "object", + "properties" : { + "type" : { + "type" : "string" }, - "subtype": { - "type": "string" + "subtype" : { + "type" : "string" }, - "type": { - "type": "string" + "parameters" : { + "type" : "object", + "additionalProperties" : { + "type" : "string" + } }, - "wildcardSubtype": { - "type": "boolean" + "wildcardType" : { + "type" : "boolean" }, - "wildcardType": { - "type": "boolean" + "wildcardSubtype" : { + "type" : "boolean" } - }, - "type": "object" - }, - "messageBodyWorkers": { - "$ref": "#/components/schemas/MessageBodyWorkers" - }, - "name": { - "type": "string" - }, - "parameterizedHeaders": { - "additionalProperties": { - "items": { - "$ref": "#/components/schemas/ParameterizedHeader" - }, - "type": "array" - }, - "type": "object" + } }, - "parent": { - "$ref": "#/components/schemas/MultiPart" + "messageBodyWorkers" : { + "$ref" : "#/components/schemas/MessageBodyWorkers" }, - "providers": { - "type": "object" + "parent" : { + "$ref" : "#/components/schemas/MultiPart" }, - "simple": { - "type": "boolean" + "providers" : { + "type" : "object" }, - "value": { - "type": "string" + "parameterizedHeaders" : { + "type" : "object", + "additionalProperties" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ParameterizedHeader" + } + } } - }, - "type": "object" + } }, - "FormDataContentDisposition": { - "properties": { - "creationDate": { - "format": "date-time", - "type": "string" - }, - "fileName": { - "type": "string" - }, - "modificationDate": { - "format": "date-time", - "type": "string" + "ContentDisposition" : { + "type" : "object", + "properties" : { + "type" : { + "type" : "string" + }, + "parameters" : { + "type" : "object", + "additionalProperties" : { + "type" : "string" + } }, - "name": { - "type": "string" + "fileName" : { + "type" : "string" }, - "parameters": { - "additionalProperties": { - "type": "string" - }, - "type": "object" + "creationDate" : { + "type" : "string", + "format" : "date-time" }, - "readDate": { - "format": "date-time", - "type": "string" + "modificationDate" : { + "type" : "string", + "format" : "date-time" }, - "size": { - "format": "int64", - "type": "integer" + "readDate" : { + "type" : "string", + "format" : "date-time" }, - "type": { - "type": "string" + "size" : { + "type" : "integer", + "format" : "int64" } - }, - "type": "object" - }, - "MessageBodyWorkers": { - "type": "object" + } }, - "MultiPart": { - "properties": { - "bodyParts": { - "items": { - "$ref": "#/components/schemas/BodyPart" - }, - "type": "array" - }, - "contentDisposition": { - "$ref": "#/components/schemas/ContentDisposition" - }, - "entity": { - "type": "object" + "FormDataBodyPart" : { + "type" : "object", + "properties" : { + "contentDisposition" : { + "$ref" : "#/components/schemas/ContentDisposition" + }, + "entity" : { + "type" : "object" + }, + "headers" : { + "type" : "object", + "additionalProperties" : { + "type" : "array", + "items" : { + "type" : "string" + } + } }, - "headers": { - "additionalProperties": { - "items": { - "type": "string" - }, - "type": "array" - }, - "type": "object" - }, - "mediaType": { - "properties": { - "parameters": { - "additionalProperties": { - "type": "string" - }, - "type": "object" + "mediaType" : { + "type" : "object", + "properties" : { + "type" : { + "type" : "string" }, - "subtype": { - "type": "string" + "subtype" : { + "type" : "string" }, - "type": { - "type": "string" + "parameters" : { + "type" : "object", + "additionalProperties" : { + "type" : "string" + } }, - "wildcardSubtype": { - "type": "boolean" + "wildcardType" : { + "type" : "boolean" }, - "wildcardType": { - "type": "boolean" + "wildcardSubtype" : { + "type" : "boolean" } - }, - "type": "object" + } }, - "messageBodyWorkers": { - "$ref": "#/components/schemas/MessageBodyWorkers" + "messageBodyWorkers" : { + "$ref" : "#/components/schemas/MessageBodyWorkers" }, - "parameterizedHeaders": { - "additionalProperties": { - "items": { - "$ref": "#/components/schemas/ParameterizedHeader" - }, - "type": "array" - }, - "type": "object" + "parent" : { + "$ref" : "#/components/schemas/MultiPart" }, - "parent": { - "$ref": "#/components/schemas/MultiPart" + "providers" : { + "type" : "object" }, - "providers": { - "type": "object" - } - }, - "type": "object" - }, - "NestedListsCheck": { - "properties": { - "containsNestedLists": { - "type": "boolean" - } - }, - "type": "object" - }, - "PageInfo": { - "properties": { - "content": { - "type": "string" + "name" : { + "type" : "string" }, - "number": { - "format": "int32", - "type": "integer" - } - }, - "type": "object" - }, - "ParameterizedHeader": { - "properties": { - "parameters": { - "additionalProperties": { - "type": "string" - }, - "type": "object" + "value" : { + "type" : "string" + }, + "formDataContentDisposition" : { + "$ref" : "#/components/schemas/FormDataContentDisposition" + }, + "simple" : { + "type" : "boolean" }, - "value": { - "type": "string" + "parameterizedHeaders" : { + "type" : "object", + "additionalProperties" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ParameterizedHeader" + } + } } - }, - "type": "object" + } }, - "Revision": { - "properties": { - "author": { - "type": "string" + "FormDataContentDisposition" : { + "type" : "object", + "properties" : { + "type" : { + "type" : "string" + }, + "parameters" : { + "type" : "object", + "additionalProperties" : { + "type" : "string" + } }, - "baseline": { - "type": "string" + "fileName" : { + "type" : "string" }, - "date": { - "type": "string" + "creationDate" : { + "type" : "string", + "format" : "date-time" }, - "description": { - "type": "string" + "modificationDate" : { + "type" : "string", + "format" : "date-time" }, - "name": { - "type": "string" - } - }, - "type": "object" - }, - "SettingName": { - "properties": { - "name": { - "type": "string" + "readDate" : { + "type" : "string", + "format" : "date-time" + }, + "size" : { + "type" : "integer", + "format" : "int64" }, - "scope": { - "type": "string" + "name" : { + "type" : "string" } - }, - "type": "object" + } }, - "SettingsModel": { - "properties": { - "bundleTimestamp": { - "type": "string" - } - }, - "type": "object" + "MessageBodyWorkers" : { + "type" : "object" }, - "Version": { - "properties": { - "automaticModuleName": { - "type": "string" - }, - "bundleBuildTimestamp": { - "type": "string" + "MultiPart" : { + "type" : "object", + "properties" : { + "contentDisposition" : { + "$ref" : "#/components/schemas/ContentDisposition" + }, + "entity" : { + "type" : "object" + }, + "headers" : { + "type" : "object", + "additionalProperties" : { + "type" : "array", + "items" : { + "type" : "string" + } + } }, - "bundleBuildTimestampDigitsOnly": { - "type": "string" + "mediaType" : { + "type" : "object", + "properties" : { + "type" : { + "type" : "string" + }, + "subtype" : { + "type" : "string" + }, + "parameters" : { + "type" : "object", + "additionalProperties" : { + "type" : "string" + } + }, + "wildcardType" : { + "type" : "boolean" + }, + "wildcardSubtype" : { + "type" : "boolean" + } + } }, - "bundleName": { - "type": "string" + "messageBodyWorkers" : { + "$ref" : "#/components/schemas/MessageBodyWorkers" }, - "bundleVendor": { - "type": "string" + "parent" : { + "$ref" : "#/components/schemas/MultiPart" }, - "bundleVersion": { - "type": "string" + "providers" : { + "type" : "object" }, - "projectURL": { - "type": "string" + "bodyParts" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/BodyPart" + } }, - "supportEmail": { - "type": "string" + "parameterizedHeaders" : { + "type" : "object", + "additionalProperties" : { + "type" : "array", + "items" : { + "$ref" : "#/components/schemas/ParameterizedHeader" + } + } } - }, - "type": "object" + } }, - "WebhooksStatus": { - "properties": { - "enabled": { - "type": "boolean" - } - }, - "type": "object" - }, - "WidthValidationResult": { - "properties": { - "invalidPages": { - "items": { - "$ref": "#/components/schemas/PageInfo" - }, - "type": "array" - }, - "suspiciousWorkItems": { - "items": { - "$ref": "#/components/schemas/WorkItemRefData" - }, - "type": "array" + "ParameterizedHeader" : { + "type" : "object", + "properties" : { + "value" : { + "type" : "string" + }, + "parameters" : { + "type" : "object", + "additionalProperties" : { + "type" : "string" + } } - }, - "type": "object" + } }, - "WorkItemRefData": { - "properties": { - "id": { - "type": "string" - }, - "layout": { - "type": "string" - }, - "link": { - "type": "string" - }, - "project": { - "type": "string" - }, - "revision": { - "type": "string" + "WebhooksStatus" : { + "type" : "object", + "properties" : { + "enabled" : { + "type" : "boolean" } - }, - "type": "object" + } } } } -} +} \ No newline at end of file diff --git a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/ConfigurationInternalController.java b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/ConfigurationInternalController.java index 14d7d30..6f8415c 100644 --- a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/ConfigurationInternalController.java +++ b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/ConfigurationInternalController.java @@ -10,6 +10,10 @@ import ch.sbb.polarion.extension.pdf.exporter.util.configuration.WeasyPrintStatusProvider; import io.swagger.v3.oas.annotations.Hidden; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.media.ArraySchema; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; import org.jetbrains.annotations.NotNull; import javax.ws.rs.DefaultValue; @@ -27,7 +31,15 @@ public class ConfigurationInternalController { @GET @Produces(MediaType.APPLICATION_JSON) @Path("/configuration/default-settings") - @Operation(summary = "Checks default settings configuration") + @Operation( + summary = "Checks default settings configuration", + responses = { + @ApiResponse(responseCode = "200", + description = "Successfully retrieved default settings configuration", + content = @Content(schema = @Schema(implementation = ConfigurationStatus.class)) + ) + } + ) public @NotNull ConfigurationStatus checkDefaultSettings(@QueryParam("scope") @DefaultValue("") String scope) { return new DefaultSettingsStatusProvider().getStatus(ConfigurationStatusProvider.Context.builder().scope(scope).build()); } @@ -35,7 +47,15 @@ public class ConfigurationInternalController { @GET @Produces(MediaType.APPLICATION_JSON) @Path("/configuration/document-properties-pane-config") - @Operation(summary = "Checks document properties pane configuration") + @Operation( + summary = "Checks document properties pane configuration", + responses = { + @ApiResponse(responseCode = "200", + description = "Successfully retrieved document properties pane configuration", + content = @Content(schema = @Schema(implementation = ConfigurationStatus.class)) + ) + } + ) public @NotNull ConfigurationStatus checkDocumentPropertiesPaneConfig(@QueryParam("scope") @DefaultValue("") String scope) { return new DocumentPropertiesPaneStatusProvider().getStatus(ConfigurationStatusProvider.Context.builder().scope(scope).build()); } @@ -43,7 +63,15 @@ public class ConfigurationInternalController { @GET @Produces(MediaType.APPLICATION_JSON) @Path("/configuration/dle-toolbar-config") - @Operation(summary = "Checks DLE Toolbar configuration") + @Operation( + summary = "Checks DLE Toolbar configuration", + responses = { + @ApiResponse(responseCode = "200", + description = "Successfully retrieved DLE Toolbar configuration", + content = @Content(schema = @Schema(implementation = ConfigurationStatus.class)) + ) + } + ) public @NotNull ConfigurationStatus checkDleToolbarConfig() { return new DleToolbarStatusProvider().getStatus(ConfigurationStatusProvider.Context.builder().build()); } @@ -51,7 +79,15 @@ public class ConfigurationInternalController { @GET @Produces(MediaType.APPLICATION_JSON) @Path("/configuration/live-report-config") - @Operation(summary = "Checks Live Report configuration") + @Operation( + summary = "Checks Live Report configuration", + responses = { + @ApiResponse(responseCode = "200", + description = "Successfully retrieved Live Report configuration", + content = @Content(schema = @Schema(implementation = ConfigurationStatus.class)) + ) + } + ) public @NotNull ConfigurationStatus checkLiveReportConfig() { return new LiveReportMainHeadStatusProvider().getStatus(ConfigurationStatusProvider.Context.builder().build()); } @@ -59,7 +95,16 @@ public class ConfigurationInternalController { @GET @Produces(MediaType.APPLICATION_JSON) @Path("/configuration/cors-config") - @Operation(summary = "Checks CORS configuration") + @Operation( + summary = "Checks CORS configuration", + description = "Retrieves the status of the CORS configuration.", + responses = { + @ApiResponse(responseCode = "200", + description = "Successfully retrieved CORS configuration", + content = @Content(schema = @Schema(implementation = ConfigurationStatus.class)) + ) + } + ) public @NotNull ConfigurationStatus checkCORSConfig() { return new CORSStatusProvider().getStatus(ConfigurationStatusProvider.Context.builder().build()); } @@ -67,7 +112,17 @@ public class ConfigurationInternalController { @GET @Produces(MediaType.APPLICATION_JSON) @Path("/configuration/weasyprint") - @Operation(summary = "Checks WeasyPrint configuration") + @Operation( + summary = "Checks WeasyPrint configuration", + description = "Retrieves the status of the WeasyPrint configuration.", + responses = { + @ApiResponse(responseCode = "200", + description = "Successfully retrieved WeasyPrint configuration", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = ConfigurationStatus.class))) + ) + } + ) + public @NotNull List checkWeasyPrint() { return new WeasyPrintStatusProvider().getStatuses(ConfigurationStatusProvider.Context.builder().build()); } diff --git a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/ConverterInternalController.java b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/ConverterInternalController.java index 103fc9e..2a4514b 100644 --- a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/ConverterInternalController.java +++ b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/ConverterInternalController.java @@ -22,6 +22,8 @@ import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.parameters.RequestBody; import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.tags.Tag; import org.jetbrains.annotations.VisibleForTesting; @@ -30,7 +32,6 @@ import javax.ws.rs.BadRequestException; import javax.ws.rs.Consumes; import javax.ws.rs.GET; -import javax.ws.rs.InternalServerErrorException; import javax.ws.rs.POST; import javax.ws.rs.Path; import javax.ws.rs.PathParam; @@ -49,6 +50,7 @@ @Hidden @Path("/internal") +@Tag(name = "PDF Processing") @SuppressWarnings("java:S1200") public class ConverterInternalController { @@ -96,8 +98,13 @@ public ConverterInternalController() { @Path("/convert") @Consumes(MediaType.APPLICATION_JSON) @Produces("application/pdf") - @Tag(name = "PDF Processing") @Operation(summary = "Returns requested Polarion's document converted to PDF", + requestBody = @RequestBody(description = "Export parameters to generate the PDF", + required = true, + content = @Content(schema = @Schema(implementation = ExportParams.class), + mediaType = MediaType.APPLICATION_JSON + ) + ), responses = { @ApiResponse(responseCode = "200", description = "Content of PDF document as a byte array", @@ -114,8 +121,14 @@ public Response convertToPdf(ExportParams exportParams) { @Path("/prepared-html-content") @Consumes(MediaType.APPLICATION_JSON) @Produces(MediaType.TEXT_HTML) - @Tag(name = "PDF Processing") @Operation(summary = "Returns prepared HTML which will be used for PDF conversion using WeasyPrint", + requestBody = @RequestBody(description = "Export parameters to generate the PDF", + required = true, + content = @Content( + schema = @Schema(implementation = ExportParams.class), + mediaType = MediaType.APPLICATION_JSON + ) + ), responses = { @ApiResponse(responseCode = "200", description = "Prepared HTML content", @@ -130,8 +143,13 @@ public String prepareHtmlContent(ExportParams exportParams) { @POST @Path("/convert/jobs") @Consumes(MediaType.APPLICATION_JSON) - @Tag(name = "PDF Processing") @Operation(summary = "Starts asynchronous conversion job of Polarion's document to PDF", + requestBody = @RequestBody(description = "Export parameters to generate the PDF", + required = true, + content = @Content(schema = @Schema(implementation = ExportParams.class), + mediaType = MediaType.APPLICATION_JSON + ) + ), responses = { @ApiResponse(responseCode = "202", description = "Conversion process is started, job URI is returned in Location header" @@ -149,21 +167,19 @@ public Response startPdfConverterJob(ExportParams exportParams) { @GET @Path("/convert/jobs/{id}") @Produces(MediaType.APPLICATION_JSON) - @Tag(name = "PDF Processing") @Operation(summary = "Returns PDF conversion job status", responses = { // OpenAPI response MediaTypes for 303 and 202 response codes are generic to satisfy automatic redirect in SwaggerUI @ApiResponse(responseCode = "303", description = "Conversion job is finished successfully, Location header contains result URL", - content = {@Content(mediaType = "application/*")} + content = {@Content(mediaType = "application/*", schema = @Schema(implementation = ConverterJobDetails.class))} ), @ApiResponse(responseCode = "202", description = "Conversion job is still in progress", - content = {@Content(mediaType = "application/*")} + content = {@Content(mediaType = "application/*", schema = @Schema(implementation = ConverterJobDetails.class))} ), @ApiResponse(responseCode = "409", - description = "Conversion job is failed or cancelled", - content = {@Content(mediaType = MediaType.APPLICATION_JSON)} + description = "Conversion job is failed or cancelled" ), @ApiResponse(responseCode = "404", description = "Conversion job id is unknown" @@ -192,7 +208,6 @@ public Response getPdfConverterJobStatus(@PathParam("id") String jobId) { @GET @Path("/convert/jobs/{id}/result") @Produces("application/pdf") - @Tag(name = "PDF Processing") @Operation(summary = "Returns PDF conversion job result", responses = { @ApiResponse(responseCode = "200", @@ -220,12 +235,11 @@ public Response getPdfConverterJobResult(@PathParam("id") String jobId) { @GET @Path("/convert/jobs") @Produces("application/json") - @Tag(name = "PDF Processing") @Operation(summary = "Returns all active PDF conversion jobs statuses", responses = { @ApiResponse(responseCode = "200", description = "Conversion jobs statuses", - content = {@Content(mediaType = "application/json")} + content = {@Content(mediaType = "application/json", schema = @Schema(implementation = Map.class))} ) }) public Response getAllPdfConverterJobs() { @@ -243,7 +257,6 @@ public Response getAllPdfConverterJobs() { @Path("/convert/html") @Consumes(MediaType.TEXT_HTML) @Produces("application/pdf") - @Tag(name = "PDF Processing") @Operation(summary = "Converts input HTML to PDF", responses = { @ApiResponse(responseCode = "200", @@ -265,8 +278,13 @@ public Response convertHtmlToPdf( @Path("/validate") @Consumes(MediaType.APPLICATION_JSON) @Produces(MediaType.APPLICATION_JSON) - @Tag(name = "PDF Processing") - @Operation(summary = "Validates if requested Polarion's document been converted to PDF doesn't contain pages which content exceeds page's width") + @Operation(summary = "Validates if requested Polarion's document been converted to PDF doesn't contain pages which content exceeds page's width", + responses = { + @ApiResponse(responseCode = "200", + description = "Validation result", + content = {@Content(mediaType = "application/json", schema = @Schema(implementation = WidthValidationResult.class))} + ) + }) public WidthValidationResult validatePdfWidth( ExportParams exportParams, @Parameter(description = "Limit of 'invalid' pages in response", required = true) @QueryParam("max-results") int maxResults) { @@ -280,16 +298,26 @@ public WidthValidationResult validatePdfWidth( @Path("/checknestedlists") @Consumes(MediaType.APPLICATION_JSON) @Produces(MediaType.APPLICATION_JSON) - @Tag(name = "PDF Processing") - @Operation(summary = "Checks whether document contains nested lists") + @Operation( + summary = "Checks whether document contains nested lists", + requestBody = @RequestBody( + description = "Export parameters used to locate and check the document for nested lists", + required = true, + content = @Content(schema = @Schema(implementation = ExportParams.class) + ) + ), + responses = { + @ApiResponse( + responseCode = "200", + description = "Check completed successfully, returning whether nested lists are present", + content = @Content(mediaType = "application/json", schema = @Schema(implementation = NestedListsCheck.class)) + ) + } + ) @SuppressWarnings("java:S1166") public NestedListsCheck checkNestedLists(ExportParams exportParams) { - try { - boolean containsNestedLists = liveDocHelper.documentContainsNestedNumberedLists(exportParams); - return NestedListsCheck.builder().containsNestedLists(containsNestedLists).build(); - } catch (Exception e) { - throw new InternalServerErrorException(e.getMessage()); - } + boolean containsNestedLists = liveDocHelper.documentContainsNestedNumberedLists(exportParams); + return NestedListsCheck.builder().containsNestedLists(containsNestedLists).build(); } private void validateExportParameters(ExportParams exportParams) { diff --git a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/SettingsInternalController.java b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/SettingsInternalController.java index b6f683c..4922986 100644 --- a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/SettingsInternalController.java +++ b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/SettingsInternalController.java @@ -10,6 +10,8 @@ import ch.sbb.polarion.extension.pdf.exporter.util.LocalizationHelper; import io.swagger.v3.oas.annotations.Hidden; import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.responses.ApiResponse; +import io.swagger.v3.oas.annotations.security.SecurityRequirement; import io.swagger.v3.oas.annotations.tags.Tag; import net.sf.okapi.lib.xliff2.reader.XLIFFReader; import org.glassfish.jersey.media.multipart.FormDataBodyPart; @@ -37,16 +39,21 @@ @Hidden @Path("/internal") +@Tag(name = "Settings", description = "Operations related to PDF-exporter settings management") +@SecurityRequirement(name = "bearerAuth") public class SettingsInternalController { - private Set predefinedCoverPageTemplates; private final PdfExporterPolarionService pdfExporterPolarionService = new PdfExporterPolarionService(); + private Set predefinedCoverPageTemplates; @GET @Path("/settings/localization/names/{name}/download") @Produces(MediaType.APPLICATION_XML) - @Tag(name = "Settings") - @Operation(summary = "Downloads localization values by name of localization settings") + @Operation(summary = "Downloads localization values by name of localization settings", + responses = { + @ApiResponse(responseCode = "200", description = "Localization file downloaded successfully") + } + ) public Response downloadTranslations( @PathParam("name") String name, @QueryParam("language") String language, @@ -67,8 +74,11 @@ public Response downloadTranslations( @Path("/settings/localization/upload") @Consumes(MediaType.MULTIPART_FORM_DATA) @Produces(MediaType.APPLICATION_JSON) - @Tag(name = "Settings") - @Operation(summary = "Uploads localization values") + @Operation(summary = "Uploads localization values", + responses = { + @ApiResponse(responseCode = "200", description = "Localization file uploaded successfully") + } + ) public Map uploadTranslations( @FormDataParam("file") FormDataBodyPart file, @QueryParam("language") String language, @@ -83,8 +93,11 @@ public Map uploadTranslations( @GET @Path("/settings/cover-page/templates") @Produces(MediaType.APPLICATION_JSON) - @Tag(name = "Settings") - @Operation(summary = "Get list of cover page predefined template names") + @Operation(summary = "Get list of cover page predefined template names", + responses = { + @ApiResponse(responseCode = "200", description = "Template names retrieved successfully") + } + ) public Collection getCoverPageTemplateNames() { if (predefinedCoverPageTemplates == null) { predefinedCoverPageTemplates = new CoverPageSettings().getPredefinedTemplates(); @@ -94,8 +107,11 @@ public Collection getCoverPageTemplateNames() { @POST @Path("/settings/cover-page/templates/{template}") - @Tag(name = "Settings") - @Operation(summary = "Persist content of cover page predefined template") + @Operation(summary = "Persist content of cover page predefined template", + responses = { + @ApiResponse(responseCode = "200", description = "Template persisted successfully") + } + ) public void persistCoverPageTemplate(@PathParam("template") String template, @QueryParam("scope") String scope) { if (!getCoverPageTemplateNames().contains(template)) { throw new NotFoundException(String.format("There's no predefined template with name '%s'", template)); @@ -114,8 +130,11 @@ public void persistCoverPageTemplate(@PathParam("template") String template, @Qu @DELETE @Path("/settings/cover-page/names/{name}/images") @Produces(MediaType.APPLICATION_JSON) - @Tag(name = "Settings") - @Operation(summary = "Deletes images in SVN linked to specified cover page within specified scope (global or certain project)") + @Operation(summary = "Deletes images in SVN linked to specified cover page within specified scope (global or certain project)", + responses = { + @ApiResponse(responseCode = "200", description = "Images deleted successfully") + } + ) public void deleteImages(@PathParam("name") String coverPageName, @QueryParam("scope") @DefaultValue("") String scope) { new CoverPageSettings().deleteCoverPageImages(coverPageName, scope); } @@ -124,7 +143,11 @@ public void deleteImages(@PathParam("name") String coverPageName, @QueryParam("s @Path("/settings/style-package/suitable-names") @Produces(MediaType.APPLICATION_JSON) @Tag(name = "Settings") - @Operation(summary = "Get list of style packages suitable for a document") + @Operation(summary = "Get list of style packages suitable for a document", + responses = { + @ApiResponse(responseCode = "200", description = "Successfully retrieved the list of style package names") + } + ) public Collection getSuitableStylePackageNames(@QueryParam("projectId") String projectId, @QueryParam("spaceId") String spaceId, @QueryParam("documentName") String documentName) { if (projectId == null || spaceId == null || documentName == null) { throw new BadRequestException("Parameters 'projectId', 'spaceId', 'documentName' are required'"); diff --git a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/UtilityResourcesInternalController.java b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/UtilityResourcesInternalController.java index 6bd622b..ab57bd0 100644 --- a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/UtilityResourcesInternalController.java +++ b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/controller/UtilityResourcesInternalController.java @@ -12,6 +12,10 @@ import io.swagger.v3.oas.annotations.Hidden; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.media.ArraySchema; +import io.swagger.v3.oas.annotations.media.Content; +import io.swagger.v3.oas.annotations.media.Schema; +import io.swagger.v3.oas.annotations.responses.ApiResponse; import io.swagger.v3.oas.annotations.tags.Tag; import javax.ws.rs.Consumes; @@ -28,6 +32,7 @@ @Hidden @Path("/internal") +@Tag(name = "Utility resources") public class UtilityResourcesInternalController { private final PdfExporterPolarionService pdfExporterPolarionService; @@ -43,9 +48,15 @@ public UtilityResourcesInternalController(PdfExporterPolarionService pdfExporter @GET @Path("/link-role-names") @Produces(MediaType.APPLICATION_JSON) - @Tag(name = "Utility resources") - @Operation(summary = "Gets list of possible WorkItem link role names in specified project scope") - public List readLinkRoleNames(@Parameter(description = "Project scope in form project//") @QueryParam("scope") String scope) { + @Operation(summary = "Gets list of possible WorkItem link role names in specified project scope", + responses = { + @ApiResponse(responseCode = "200", + description = "Successfully retrieved list of link role names", + content = @Content(array = @ArraySchema(schema = @Schema(implementation = String.class))) + ) + } + ) + public List readLinkRoleNames(@Parameter(description = "Project scope in form project//", required = true) @QueryParam("scope") String scope) { ITrackerProject project = pdfExporterPolarionService.getProjectFromScope(scope); if (project != null) { return EnumValuesProvider.getAllLinkRoleNames(project); @@ -56,8 +67,11 @@ public List readLinkRoleNames(@Parameter(description = "Project scope in @GET @Path("/document-language") @Produces(MediaType.TEXT_PLAIN) - @Tag(name = "Utility resources") - @Operation(summary = "Gets language of specified Polarion's document, defined in its custom field 'docLanguage'") + @Operation(summary = "Gets language of specified Polarion's document, defined in its custom field 'docLanguage'", + responses = { + @ApiResponse(responseCode = "200", description = "Successfully retrieved document language") + } + ) public String getDocumentLanguage(@QueryParam("projectId") String projectId, @QueryParam("spaceId") String spaceId, @QueryParam("documentName") String documentName, @QueryParam("revision") String revision) { IModule module = pdfExporterPolarionService.getModule(projectId, spaceId, documentName, revision); @@ -68,8 +82,11 @@ public String getDocumentLanguage(@QueryParam("projectId") String projectId, @Qu @GET @Path("/projects/{projectId}/name") @Produces(MediaType.TEXT_PLAIN) - @Tag(name = "Utility resources") - @Operation(summary = "Gets name of specified Polarion's project") + @Operation(summary = "Gets name of specified Polarion's project", + responses = { + @ApiResponse(responseCode = "200", description = "Successfully retrieved project name") + } + ) public String getProjectName(@PathParam("projectId") String projectId) { return pdfExporterPolarionService.getProject(projectId).getName(); } @@ -78,8 +95,11 @@ public String getProjectName(@PathParam("projectId") String projectId) { @Path("/export-filename") @Consumes(MediaType.APPLICATION_JSON) @Produces(MediaType.TEXT_PLAIN) - @Tag(name = "Utility resources") - @Operation(summary = "Gets a filename, prepared with velocity and placeholders") + @Operation(summary = "Gets a filename, prepared with velocity and placeholders", + responses = { + @ApiResponse(responseCode = "200", description = "Successfully generated filename") + } + ) public String getFileName(@QueryParam("locationPath") String locationPath, @QueryParam("revision") String revision, @QueryParam("documentType") DocumentType documentType, @QueryParam("scope") String scope) { return new DocumentFileNameHelper(pdfExporterPolarionService).getDocumentFileName(locationPath, revision, documentType, scope); } @@ -88,7 +108,11 @@ public String getFileName(@QueryParam("locationPath") String locationPath, @Quer @Path("/webhooks/status") @Produces(MediaType.APPLICATION_JSON) @Tag(name = "Utility resources") - @Operation(summary = "Gets webhooks status - if they are enabled or not") + @Operation(summary = "Gets webhooks status - if they are enabled or not", + responses = { + @ApiResponse(responseCode = "200", description = "Webhooks status") + } + ) public WebhooksStatus getWebhooksStatus() { return WebhooksStatus.builder().enabled(PdfExporterExtensionConfiguration.getInstance().getWebhooksEnabled()).build(); } diff --git a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/ExportMetaInfoCallback.java b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/ExportMetaInfoCallback.java index 7c31c01..c5cacfa 100644 --- a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/ExportMetaInfoCallback.java +++ b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/ExportMetaInfoCallback.java @@ -1,10 +1,16 @@ package ch.sbb.polarion.extension.pdf.exporter.rest.model; +import io.swagger.v3.oas.annotations.media.Schema; import lombok.Data; import java.util.List; @Data +@Schema(description = "Callback class containing metadata information related to export") public class ExportMetaInfoCallback { + + @Schema(description = "List of work items linked to the export process", + implementation = WorkItemRefData.class) private List linkedWorkItems; } + diff --git a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/NestedListsCheck.java b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/NestedListsCheck.java index 4358f31..c4226de 100644 --- a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/NestedListsCheck.java +++ b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/NestedListsCheck.java @@ -1,10 +1,13 @@ package ch.sbb.polarion.extension.pdf.exporter.rest.model; +import io.swagger.v3.oas.annotations.media.Schema; import lombok.Builder; import lombok.Data; @Data @Builder +@Schema(description = "Check result indicating whether nested lists are present") public class NestedListsCheck { + @Schema(description = "Indicates whether the content contains nested lists") private boolean containsNestedLists; } diff --git a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/WidthValidationResult.java b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/WidthValidationResult.java index 5edd4b3..5205824 100644 --- a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/WidthValidationResult.java +++ b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/WidthValidationResult.java @@ -1,6 +1,7 @@ package ch.sbb.polarion.extension.pdf.exporter.rest.model; import com.fasterxml.jackson.annotation.JsonInclude; +import io.swagger.v3.oas.annotations.media.Schema; import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; @@ -18,9 +19,15 @@ @ToString @EqualsAndHashCode @JsonInclude(JsonInclude.Include.NON_NULL) +@Schema(description = "Result of the width validation process") public class WidthValidationResult { + @Schema(description = "List of pages that failed the width validation", + implementation = PageInfo.class) private List invalidPages = new LinkedList<>(); + + @Schema(description = "List of work items that are considered suspicious based on the validation", + implementation = WorkItemRefData.class) private List suspiciousWorkItems = new LinkedList<>(); @Data @@ -30,8 +37,13 @@ public class WidthValidationResult { @ToString @EqualsAndHashCode @JsonInclude(JsonInclude.Include.NON_NULL) + @Schema(description = "Information about a specific page that failed validation, including its number and content.") public static class PageInfo { + + @Schema(description = "The number of the page that failed validation") private int number; + + @Schema(description = "The encoded content of the page that failed validation") private String content; } } diff --git a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/WorkItemRefData.java b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/WorkItemRefData.java index ed869a6..789a2ef 100644 --- a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/WorkItemRefData.java +++ b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/WorkItemRefData.java @@ -2,6 +2,7 @@ import ch.sbb.polarion.extension.generic.regex.RegexMatcher; import com.fasterxml.jackson.annotation.JsonProperty; +import io.swagger.v3.oas.annotations.media.Schema; import lombok.AllArgsConstructor; import lombok.Data; import lombok.NoArgsConstructor; @@ -16,10 +17,18 @@ @Data @AllArgsConstructor @NoArgsConstructor +@Schema(description = "Data class representing a reference to a work item, including ID, project, layout, and revision") public class WorkItemRefData { + @Schema(description = "The unique identifier of the Work item") private String id; + + @Schema(description = "The unique identifier of the project to which the Work item belongs") private String project; + + @Schema(description = "Work item layout") private String layout; + + @Schema(description = "The revision number of the Work item") private String revision; /** @@ -37,7 +46,7 @@ public static List extractListFromHtml(String html, String defa ref.setLayout(regexEngine.group("layout")); ref.setRevision(regexEngine.group("revision")); refs.add(ref); - }); + }); return new ArrayList<>(refs); } diff --git a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/DocumentType.java b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/DocumentType.java index 40c628e..9ce39d5 100644 --- a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/DocumentType.java +++ b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/DocumentType.java @@ -1,10 +1,17 @@ package ch.sbb.polarion.extension.pdf.exporter.rest.model.conversion; import com.fasterxml.jackson.annotation.JsonCreator; +import io.swagger.v3.oas.annotations.media.Schema; +@Schema(description = "Type of the document") public enum DocumentType { + @Schema(description = "Live document") DOCUMENT, + + @Schema(description = "Wiki page") WIKI, + + @Schema(description = "Live report") REPORT; @SuppressWarnings("unused") diff --git a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/ExportParams.java b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/ExportParams.java index 4e8b0f4..7b5d29b 100644 --- a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/ExportParams.java +++ b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/ExportParams.java @@ -1,5 +1,6 @@ package ch.sbb.polarion.extension.pdf.exporter.rest.model.conversion; +import io.swagger.v3.oas.annotations.media.Schema; import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; @@ -13,32 +14,83 @@ @NoArgsConstructor @AllArgsConstructor public class ExportParams { + @Schema(name = "Project ID", example = "elibrary", description = "The unique identifier for the project") private String projectId; + + @Schema(name = "Location path", required = true, description = "Document path for export") private String locationPath; + + @Schema(description = "The specific revision of the document to export") private String revision; + + @Schema(description = "The type of document to export", example = "DOCUMENT") private DocumentType documentType; + + @Schema(description = "Cover page settings name") private String coverPage; + + @Schema(description = "CSS settings name") private String css; + + @Schema(description = "Header Footer settings name") private String headerFooter; + + @Schema(description = "Localization settings name") private String localization; + + @Schema(description = "Webhooks settings name") private String webhooks; + + @Schema(description = "Color to be used for headers in the document. By default dark blue color (Polarion's default)") private String headersColor; + + @Schema(description = "The orientation of the exported document", defaultValue = "PORTRAIT") private Orientation orientation = Orientation.PORTRAIT; + + @Schema(description = "The paper size of the exported document", defaultValue = "A4") private PaperSize paperSize = PaperSize.A4; + + @Schema(description = "Content should be scaled to fit the page", defaultValue = "true") private boolean fitToPage = true; + + @Schema(description = "Comments should be rendered in the exported document", defaultValue = "true") private boolean enableCommentsRendering = true; + + @Schema(description = "Watermark content to be applied to the document") private boolean watermark; + + @Schema(description = "Referenced work items should be marked in the document") private boolean markReferencedWorkitems; + + @Schema(description = "Empty chapters should be removed from the document") private boolean cutEmptyChapters; + + @Schema(description = "Empty work item attributes should be removed from the document", defaultValue = "true") private boolean cutEmptyWIAttributes = true; + + @Schema(description = "Local Polarion URLs should be removed from the document") private boolean cutLocalUrls; + + @Schema(description = "HTML presentational hints should be followed", defaultValue = "true") private boolean followHTMLPresentationalHints = true; + + @Schema(description = "SCC styles to be applied to numbered lists in the document") private String numberedListStyles; + + @Schema(description = "Specific higher level chapters") private List chapters; + + @Schema(description = "Language in the exported document") private String language; + + @Schema(description = "Specific Workitem roles", example = "[\"has parent\", \"depends on\"]") private List linkedWorkitemRoles; + + @Schema(description = "Map of attributes extracted from the URL") private Map urlQueryParameters; - private String internalContent; //overrides existing content in doc + + @Schema(description = "Internal content") + private String internalContent; public DocumentType getDocumentType() { // Default to DOCUMENT diff --git a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/Orientation.java b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/Orientation.java index 5cd2752..bf247e9 100644 --- a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/Orientation.java +++ b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/Orientation.java @@ -1,17 +1,18 @@ package ch.sbb.polarion.extension.pdf.exporter.rest.model.conversion; import com.fasterxml.jackson.annotation.JsonCreator; +import io.swagger.v3.oas.annotations.media.Schema; import javax.ws.rs.WebApplicationException; import javax.ws.rs.core.Response; +@Schema(description = "Orientation of the output document") public enum Orientation { + @Schema(description = "Portrait orientation") PORTRAIT, - LANDSCAPE; - public String toCssString() { - return toString().toLowerCase(); - } + @Schema(description = "Landscape orientation") + LANDSCAPE; @JsonCreator public static Orientation fromString(String name) { @@ -25,4 +26,8 @@ public static Orientation fromString(String name) { .build()); } } + + public String toCssString() { + return toString().toLowerCase(); + } } diff --git a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/PaperSize.java b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/PaperSize.java index eb70b0c..0b0c11a 100644 --- a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/PaperSize.java +++ b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/conversion/PaperSize.java @@ -1,6 +1,7 @@ package ch.sbb.polarion.extension.pdf.exporter.rest.model.conversion; import com.fasterxml.jackson.annotation.JsonCreator; +import io.swagger.v3.oas.annotations.media.Schema; import javax.ws.rs.WebApplicationException; import javax.ws.rs.core.Response; @@ -8,6 +9,7 @@ /** * Enumeration of paper sizes supported by CSS */ +@Schema(description = "Standard paper sizes") public enum PaperSize { A5, A4, @@ -20,15 +22,6 @@ public enum PaperSize { LEGAL, LEDGER; - public String toCssString() { - return switch (this) { - case JIS_B5 -> "JIS-B5"; - case JIS_B4 -> "JIS-B4"; - case LETTER, LEGAL, LEDGER -> toString().toLowerCase(); - default -> toString(); - }; - } - @JsonCreator public static PaperSize fromString(String name) { try { @@ -41,4 +34,13 @@ public static PaperSize fromString(String name) { .build()); } } + + public String toCssString() { + return switch (this) { + case JIS_B5 -> "JIS-B5"; + case JIS_B4 -> "JIS-B4"; + case LETTER, LEGAL, LEDGER -> toString().toLowerCase(); + default -> toString(); + }; + } } diff --git a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/jobs/ConverterJobDetails.java b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/jobs/ConverterJobDetails.java index db72a86..edf30fb 100644 --- a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/jobs/ConverterJobDetails.java +++ b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/jobs/ConverterJobDetails.java @@ -1,6 +1,7 @@ package ch.sbb.polarion.extension.pdf.exporter.rest.model.jobs; import com.fasterxml.jackson.annotation.JsonInclude; +import io.swagger.v3.oas.annotations.media.Schema; import lombok.AllArgsConstructor; import lombok.Builder; import lombok.Data; @@ -11,7 +12,15 @@ @NoArgsConstructor @AllArgsConstructor @JsonInclude(JsonInclude.Include.NON_NULL) +@Schema(description = "Details of the converter job including status and error message if any") public class ConverterJobDetails { + + @Schema(description = "Current status of the converter job", + example = "IN_PROGRESS", + implementation = ConverterJobStatus.class + ) private ConverterJobStatus status; + + @Schema(description = "Error message if the conversion failed") private String errorMessage; } diff --git a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/jobs/ConverterJobStatus.java b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/jobs/ConverterJobStatus.java index 9a99232..1661166 100644 --- a/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/jobs/ConverterJobStatus.java +++ b/src/main/java/ch/sbb/polarion/extension/pdf/exporter/rest/model/jobs/ConverterJobStatus.java @@ -1,8 +1,19 @@ package ch.sbb.polarion.extension.pdf.exporter.rest.model.jobs; +import io.swagger.v3.oas.annotations.media.Schema; + +@Schema(description = "Status of the converter job") public enum ConverterJobStatus { + + @Schema(description = "The conversion is currently in progress") IN_PROGRESS, + + @Schema(description = "The conversion has finished successfully") SUCCESSFULLY_FINISHED, + + @Schema(description = "The conversion has failed") FAILED, + + @Schema(description = "The conversion was cancelled") CANCELLED -} +} \ No newline at end of file