MP OpenAPi edits

#340

Author: dmuelle

modules/ROOT/pages/documentation-openapi.adoc

@@ -13,12 +13,14 @@
 = 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 JAX-RS applications.
+MicroProfile OpenAPI helps you to generate structured documentation from your Jakarta RESTful Services or JAX-RS applications.
 
 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.
+
+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.
+
 
 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.
@@ -28,9 +30,6 @@ The JAX-RS framework handles basic API generation for JAX-RS annotations and gen
 You can use this treemap as a starting point and augment it with annotations and code to produce a complete OpenAPI document.
 Additionally, you can use this manually created documentation to generate stubs, or testable versions of code modules, such as client libraries for the API.
 
-Some deprecated annotations were removed between Microprofile OpenAPI versions 1.1 and 2.0, which might result in breaking changes between those versions.
-For more information, see the https://download.eclipse.org/microprofile/microprofile-open-api-2.0/microprofile-openapi-spec-2.0.html#release_notes_20[Release Notes for Microprofile OpenAPI 2.0].
-
 == The code-first approach
 
 In the code-first approach, you can initially generate basic API documentation of the REST API from annotations that are specified in the source code.
@@ -136,9 +135,6 @@ 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].
 
-== View API documentation
-
-The OpenAPI document can be viewed 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.
 
 [#multi-module]
 == Multiple application and multi-module application support with MicroProfile OpenAPI
@@ -209,8 +205,8 @@ When OpenAPI documentation from multiple modules is merged into a single documen
 
 - If the `externalDocs` section is not the same across all documents, it is removed from the final document.
 
+
 == See also
 
 - link:/guides/microprofile-openapi.html[Guide: Documenting RESTful APIs]
 - Guide: link:/guides/microprofile-config-intro.html[Separating configuration from code in microservices]
-- link:https://download.eclipse.org/microprofile/microprofile-open-api-2.0/microprofile-openapi-spec-2.0.html#release_notes_20[Release Notes for MicroProfile OpenAPI 2.0]

modules/reference/pages/feature/mpOpenAPI-1.1/description.adoc

@@ -0,0 +1,2 @@
+Some deprecated annotations were removed between Microprofile OpenAPI versions 1.1 and 2.0, which might result in breaking changes between those versions.
+For more information, see the https://download.eclipse.org/microprofile/microprofile-open-api-2.0/microprofile-openapi-spec-2.0.html#release_notes_20[Release Notes for Microprofile OpenAPI 2.0].

modules/reference/pages/feature/mpOpenAPI-2.0/description.adoc

@@ -0,0 +1,2 @@
+Some deprecated annotations were removed between Microprofile OpenAPI versions 1.1 and 2.0, which might result in breaking changes between those versions.
+For more information, see the https://download.eclipse.org/microprofile/microprofile-open-api-2.0/microprofile-openapi-spec-2.0.html#release_notes_20[Release Notes for Microprofile OpenAPI 2.0].