Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MP Open API update 9 #914

Merged
merged 1 commit into from
Jan 10, 2020
Merged

MP Open API update 9 #914

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions ref/general/mp-openapi.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,25 +12,25 @@
:page-type: general
= OpenAPI documentation for microservices

OpenAPI is a standardized mechanism for developers to describe REST APIs. With OpenAPI you can describe REST APIs and generate API documentation from the APIs themselves. MicroProfile OpenAPI is a specification outlined as an official set of annotations and interfaces that help developers successfully generate OpenAPI documentation for their Java RESTful APIs.
OpenAPI is a standardized mechanism to describe REST APIs. The MicroProfile OpenAPI specification is an official set of annotations and interfaces to help developers generate OpenAPI documentation for Java RESTful APIs.

You can generate the OpenAPI document in multiple ways.

== Annotations

JAX-RS annotations are processed by default with MP OpenAPI. You can augment the existing code with OpenAPI annotations, which provide detailed documentation for the REST API.
MP OpenAPI processes JAX-RS annotations by default. You can augment the existing code with OpenAPI annotations, which provide detailed documentation for the REST API.

Vendors must process all the relevant JAX-RS annotations, like @Path and @Consumes, and Java objects used as input or output to JAX-RS operations. Developers can deploy their existing JAX-RS application into a MP OpenAPI vendor and check out the output from `/openapi`.
Vendors must process the relevant JAX-RS annotations like @Path, @Consumes, and Java objects used as input or output to JAX-RS operations. Developers can deploy the existing JAX-RS application into a MP OpenAPI vendor and check out the output from `/openapi`.

Annotations like @Callback, @Components, @ParameterIn, and more are found in the Eclipse OpenAPI annotations package . For an overview of annotation, see https://download.eclipse.org/microprofile/microprofile-open-api-1.0/microprofile-openapi-spec.html#_quick_overview_of_annotations.

When the same annotation is used on a class and a method, the values from the method instance take precedence for that particular method, for example, @Server and @Tag annotations. The annotation values from the method’s parameters take precedence over corresponding annotation values from the method itself, for example, @Parameter and @RequestBody. The @Schema annotation has a complex set of possible combinations. It can be placed on POJOs and referenced from many other annotations.
When the same annotation is used on a class and a method, the values from the method instance take precedence for that particular method, for example, @Server and @Tag annotations. The annotation values from the method’s parameters take precedence over corresponding annotation values from that method, for example, @Parameter and @RequestBody. The @Schema annotation has a complex set of possible combinations, and can be placed on POJOs and referenced from several other annotations.

For examples of annotations, see link:https://github.com/eclipse/microprofile-open-api/wiki/Annotation-Samples[Annotation Samples]

== Static OpenAPI files

Take the initial output from `/openapi` as a starting point to document your APIs with Static OpenAPI files. The static files can also be written before any code, which is an approach often adopted by enterprises that want to lock-in the contract of the API. The OpenAPI document is referred as the "source of truth" in this case, by which the client and provider must abide.
Take the initial output from `/openapi` as a starting point to document APIs with Static OpenAPI files. You can write the static files before any code. Enterprises often adopt this approach to lock-in the API contract. The client and provider must abide by this OpenAPI document, referred to as the "source of truth".

You can use a static OpenAPI file in YAML format or JSON format.

Expand All @@ -40,18 +40,18 @@ For examples of Static OpenAPI files, see link:https://github.com/eclipse/microp

You can provide OpenAPI elements via Java POJOs. For a complete set of models see, link:https://github.com/eclipse/microprofile-open-api/tree/master/api/src/main/java/org/eclipse/microprofile/openapi/annotations[org.eclipse.microprofile.openapi.models] package.

Use link:https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java[OASFactory] to create all the elements of an OpenAPI tree, and the link:https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/OASModelReader.java[OASModelReader] interface to bootstrap the OpenAPI model tree used by the processing framework.
Use link:https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/OASFactory.java[OASFactory] to create the elements of an OpenAPI tree, and the link:https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/OASModelReader.java[OASModelReader] interface to bootstrap the OpenAPI model tree used by the processing framework.

For examples of OASModelReader, see link:https://github.com/eclipse/microprofile-open-api/wiki/OASModelReader-Samples[OASModelReader Samples].

== Filter

With link:https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/OASFilter.java[OASFilter], you can receive callbacks for various key OpenAPI elements. To use it, create an implementation of the interface and register it using the `mp.openapi.filter` configuration key, where the value is the fully qualified name of the filter class.
With link:https://github.com/eclipse/microprofile-open-api/blob/master/api/src/main/java/org/eclipse/microprofile/openapi/OASFilter.java[OASFilter], you can receive callbacks for various key OpenAPI elements. To use OASFilter, create an implementation of the interface and register it using the `mp.openapi.filter` configuration key, where the value is the fully qualified name of the filter class.

For examples of OASFilter, see link:https://github.com/eclipse/microprofile-open-api/wiki/OASFilter-Samples[OASFilter Samples].

== OpenAPI UI

The native OpenAPI UI is value-add from Open Liberty is that ships out of the box. This UI is built from the link:https://github.com/swagger-api/swagger-ui[Open Source Swagger UI] and renders the generated `/openapi` document into a user friendly page. It has the ability to `Try out` each endpoint, making an invocation to the back-end straight from the UI.
The native OpenAPI UI is value-add from Open Liberty that ships out of the box. This UI is built from the link:https://github.com/swagger-api/swagger-ui[Open Source Swagger UI] and renders the generated `/openapi` document into a user friendly page. It can `Try out` each endpoint, making an invocation to the back-end from the UI.

The UI, available from the endpoint `/openapi/ui` can also be link:https://www.ibm.com/support/knowledgecenter/en/SSD28V_liberty/com.ibm.websphere.wlp.core.doc/ae/twlp_api_mpopenapi_custom.html[customized].
You can also link:https://www.ibm.com/support/knowledgecenter/en/SSD28V_liberty/com.ibm.websphere.wlp.core.doc/ae/twlp_api_mpopenapi_custom.html[customize] the UI available from the endpoint `/openapi/ui` .