From 1e83c1c4f20cf39fcff840d456419e56ed1c6afb Mon Sep 17 00:00:00 2001 From: Fabio Turizo Date: Tue, 9 Aug 2022 17:35:43 -0500 Subject: [PATCH] FISH-6298 Yaml result added with the explanation about 'endpoints' --- .../MicroProfile/OpenAPI.adoc | 107 ++++++++++++++++++ .../MicroProfile/OpenAPI.adoc | 107 ++++++++++++++++++ 2 files changed, 214 insertions(+) diff --git a/community/docs/modules/ROOT/pages/Technical Documentation/MicroProfile/OpenAPI.adoc b/community/docs/modules/ROOT/pages/Technical Documentation/MicroProfile/OpenAPI.adoc index 4a59f6ce6..8439ccd8c 100644 --- a/community/docs/modules/ROOT/pages/Technical Documentation/MicroProfile/OpenAPI.adoc +++ b/community/docs/modules/ROOT/pages/Technical Documentation/MicroProfile/OpenAPI.adoc @@ -142,6 +142,113 @@ import org.eclipse.microprofile.openapi.annotations.Operation; } ---- +Here's an example of how the OpenAPI document of a sample application would look like:: +[source, yml] +---- +openapi: 3.0.0 +info: + title: A Test Application + version: "1.0" +servers: +- url: http://localhost:8080/openapi-example-1.0 + description: Default Server. +- url: https://localhost:8181/openapi-example-1.0 + description: Default Server. +paths: + /api/hello: + get: + operationId: hello-world + responses: + default: + content: + text/plain: + schema: + type: string + description: Default Response. + deprecated: false +endpoints: + /openapi-example-1.0: + - /api/hello +components: {} +---- + +[[deployed-endpoints]] +==== Deployed Endpoints + +When more than one application is deployed, a merge is done in the OpenAPI document. The resulting document will contain all application and path definitions present. To improve the its readability, an `endpoints` attribute which lists all deployed endpoints grouped by their application context roots has been added to the document. + +NOTE: The `endpoints` attribute is an proprietary Payara Platform extension and it's not portable. + +The following example shows an OpenAPI document generated when 2 different applications are deployed:: +[source, yml] +---- +openapi: 3.0.0 +info: + title: Deployed Resources + version: 1.0.0 +servers: +- url: http://localhost:8080/ClusteredSingleton + description: Default Server. +- url: https://localhost:8181/ClusteredSingleton + description: Default Server. +- url: http://localhost:8080/SimpleWAR + description: Default Server. +- url: https://localhost:8181/SimpleWAR + description: Default Server. +paths: + /resources/javaee8: + get: + operationId: ping + responses: + default: + content: + '*/*': + schema: + type: object + description: Default Response. + /resources/randomNumberGen: + get: + operationId: randomNumberGen + responses: + default: + content: + '*/*': + schema: + type: integer + description: Default Response. + /rest/request: + get: + operationId: getXml + responses: + default: + content: + text/plain: + schema: + type: string + description: Default Response. + put: + operationId: putXml + requestBody: + content: + application/xml: + schema: + type: string + responses: + default: + content: + '*/*': + schema: + type: object + description: Default Response. +endpoints: + /ClusteredSingleton: + - /resources/javaee8 + - /resources/randomNumberGen + /SimpleWAR: + - /rest/request +components: {} +---- + [[openApi-configuration]] == OpenAPI Configuration diff --git a/enterprise/docs/modules/ROOT/pages/Technical Documentation/MicroProfile/OpenAPI.adoc b/enterprise/docs/modules/ROOT/pages/Technical Documentation/MicroProfile/OpenAPI.adoc index fc7427403..bf2f1fbee 100644 --- a/enterprise/docs/modules/ROOT/pages/Technical Documentation/MicroProfile/OpenAPI.adoc +++ b/enterprise/docs/modules/ROOT/pages/Technical Documentation/MicroProfile/OpenAPI.adoc @@ -140,6 +140,113 @@ import org.eclipse.microprofile.openapi.annotations.Operation; } ---- +Here's an example of how the OpenAPI document of a sample application would look like:: +[source, yml] +---- +openapi: 3.0.0 +info: + title: A Test Application + version: "1.0" +servers: +- url: http://localhost:8080/openapi-example-1.0 + description: Default Server. +- url: https://localhost:8181/openapi-example-1.0 + description: Default Server. +paths: + /api/hello: + get: + operationId: hello-world + responses: + default: + content: + text/plain: + schema: + type: string + description: Default Response. + deprecated: false +endpoints: + /openapi-example-1.0: + - /api/hello +components: {} +---- + +[[deployed-endpoints]] +==== Deployed Endpoints + +When more than one application is deployed, a merge is done in the OpenAPI document. The resulting document will contain all application and path definitions present. To improve the its readability, an `endpoints` attribute which lists all deployed endpoints grouped by their application context roots has been added to the document. + +NOTE: The `endpoints` attribute is an proprietary Payara Platform extension and it's not portable. + +The following example shows an OpenAPI document generated when 2 different applications are deployed:: +[source, yml] +---- +openapi: 3.0.0 +info: + title: Deployed Resources + version: 1.0.0 +servers: +- url: http://localhost:8080/ClusteredSingleton + description: Default Server. +- url: https://localhost:8181/ClusteredSingleton + description: Default Server. +- url: http://localhost:8080/SimpleWAR + description: Default Server. +- url: https://localhost:8181/SimpleWAR + description: Default Server. +paths: + /resources/javaee8: + get: + operationId: ping + responses: + default: + content: + '*/*': + schema: + type: object + description: Default Response. + /resources/randomNumberGen: + get: + operationId: randomNumberGen + responses: + default: + content: + '*/*': + schema: + type: integer + description: Default Response. + /rest/request: + get: + operationId: getXml + responses: + default: + content: + text/plain: + schema: + type: string + description: Default Response. + put: + operationId: putXml + requestBody: + content: + application/xml: + schema: + type: string + responses: + default: + content: + '*/*': + schema: + type: object + description: Default Response. +endpoints: + /ClusteredSingleton: + - /resources/javaee8 + - /resources/randomNumberGen + /SimpleWAR: + - /rest/request +components: {} +---- + [[openApi-configuration]] == OpenAPI Configuration