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

Update documentation-openapi.adoc #7151

Merged
merged 1 commit into from
Dec 20, 2023
Merged

Update documentation-openapi.adoc #7151

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
21 changes: 6 additions & 15 deletions modules/ROOT/pages/documentation-openapi.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,18 +12,17 @@
:page-type: general
= API documentation with OpenAPI

MicroProfile OpenAPI is a MicroProfile community programming model for the OpenAPI specification.
MicroProfile OpenAPI helps you to generate structured documentation from your Jakarta RESTful Services or JAX-RS applications.
MicroProfile OpenAPI helps you to generate structured documentation from your Jakarta RESTful Services or JAX-RS applications. This documentation helps other microservices and developers to understand and communicate with your application.

Structured documentation helps other microservices and developers to understand and communicate with your application.
Other developers need relevant information to build an application that communicates with the REST API of your application.
MicroProfile OpenAPI facilitates this communication by generating human and machine-readable documentation on a simple interface that doesn’t require access to the source code.

You can implement MicroProfile OpenAPI for Open Liberty by enabling the feature:mpOpenAPI[display=MicroProfile OpenAPI] feature. When this feature is enabled, you can view the OpenAPI document in a browser by using the `/openapi` endpoint. For example, if your browser is on the same machine where your server is running, you can view the OpenAPI document at the http://localhost:9080/openapi or the http://localhost:9080/openapi/ui URL.
You can implement MicroProfile OpenAPI for Open Liberty by enabling the feature:mpOpenAPI[display=MicroProfile OpenAPI] feature. When this feature is enabled, you can view the OpenAPI document in a browser by using the `/openapi` endpoint. For example, if your browser is on the same machine where your server is running, you can view the OpenAPI document at the \http://localhost:9080/openapi or the \http://localhost:9080/openapi/ui URL.

To explore how to document and filter RESTful APIs from code or static files by using Open Liberty and MicroProfile OpenAPI, see the link:/guides/microprofile-openapi.html[Documenting RESTful APIs] guide.

The two main approaches to generate an OpenAPI document are the code-first approach and the design-first approach.
In the code-first approach, a developer can generate documentation of the REST API from the source code.
In the code-first approach, you can generate documentation of the REST API from the source code.
The reference document that is produced lists all the API endpoints with descriptions of how to use them.
Alternatively, in the design-first approach, you can include a pre-generated OpenAPI document that was written separately from the code.
The JAX-RS framework handles basic API generation for JAX-RS annotations and generates a skeleton OpenAPI treemap.
Expand Down Expand Up @@ -111,7 +110,7 @@ The following OpenAPI document is generated in YAML format from the OpenAPI anno

The information that is provided through the OpenAPI annotations augments the basic API documentation that is generated by the JAX-RS framework.

For more information, see the xref:reference:javadoc/microprofile-4.1-javadoc.adoc#package=org/eclipse/microprofile/openapi/annotations/package-frame.html&class=org/eclipse/microprofile/openapi/annotations/package-summary.html[MicroProfile OpenAPI Javadoc] for the available annotations.
For more information, see the xref:reference:javadoc/microprofile-6.1-javadoc.html?class=org/eclipse/microprofile/openapi/models/OpenAPI.html&package=allclasses-frame.html[MicroProfile OpenAPI Javadoc] for the available annotations.

== The design-first approach

Expand All @@ -127,14 +126,6 @@ You can augment manually created API documents by adding annotations to the code

For more information, see https://openliberty.io/guides/microprofile-openapi.html#using-pregenerated-openapi-documents[Using pregenerated OpenAPI documents].

== Filter components in and out of API documentation

If you want to update or remove certain elements and fields of the OpenAPI document you can use a filter, which is called one time after all other documentation mechanisms are finished.
Filters give the users the flexibility to modify the document.
With filters, you can implement an interface in your application.
When a component of the documentation is processed, it calls your implementation and you can either add or remove content.
For more information, see https://openliberty.io/guides/microprofile-openapi.html#filtering-the-openapi-tree-elements[Filtering the OpenAPI tree elements].


[#multi-module]
== Multiple application and multi-module application support with MicroProfile OpenAPI
Expand Down Expand Up @@ -208,5 +199,5 @@ When OpenAPI documentation from multiple modules is merged into a single documen

== See also

- link:/guides/microprofile-openapi.html[Guide: Documenting RESTful APIs]
-
- Guide: link:/guides/microprofile-config-intro.html[Separating configuration from code in microservices]