Generating REST API documentation with OpenAPI

You can generate your REST API documentation by using the openapi-3.0 feature, which supports the OpenAPI specification. Document your REST APIs, specify public and private APIs, choose to enable annotation scanning, and deploy your web applications to a Liberty server. Then, you can view the API documentation that is generated by openapi-3.0 in a browser that uses a human-friendly user interface.

Stabilized features: The OpenAPI V3 features, openapi-3.0 and openapi-3.1, are stabilized. You can continue to use the features. However, the strategic alternative is to use a MicroProfile OpenAPI feature such as mpOpenAPI-3.0.

For more information about using MicroProfile OpenAPI with Liberty, see the Open Liberty website

Before you begin

Learn about the OpenAPI V3 specification. You use YAML or JSON files to document the RESTful APIs in your applications.

You can use the Java interfaces and programming models that are available from the MicroProfile OpenAPI Specification version 1.0. The mpOpenAPI-1.0 feature implements the MicroProfile OpenAPI specification. For more information about the mpOpenAPI-1.0 and later features, see Generating REST API documentation with MicroProfile OpenAPI.

About this task

You can explore these features, such as the new user interface, annotations, and programming interfaces, with the following sample applications.

Try documenting a RESTful application using OpenAPI annotations in Java™ code using the OpenAPI V3 annotation sample application.
See an example of an OpenAPI V3 document in YAML format created with a text editor with OpenAPI V3 example document.
Extend the openapi-3.0 feature by using the io.swagger.oas.integration.OpenAPIConfigurationBuilder programming interfaces with the OpenAPIConfiguration programming interface example.

Procedure

Build the OpenAPI documentation.
You can document and build OpenAPIs in several ways:
- Specify OpenAPI annotations in Java code to augment and document an application.
- Use a text editor to document the API with OpenAPI tags and then place the completed openapi.yaml, openapi.yml, or openapi.json file in the META-INF directory of your application.
- Use the io.swagger.oas.integration.OpenAPIConfigurationBuilder programming interfaces to build the OpenAPI model from within the application. This interface, and the other related programming interfaces for OpenAPI V3, can be found in the JAR files in the /wlp/dev/api/third-party directory. For the openapi-3.0 feature to start the OpenAPIConfigurationBuilder, the application archive must have a META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder file. The content of this file is the fully qualified name of the OpenAPIConfigurationBuilder.
  For more information about the available programming interfaces, descriptions of their capabilities, and examples of their use, see OpenAPI V3 programming interfaces.
Enable the openapi-3.0 feature in the Liberty server configuration.
1. Add the openapi-3.0 feature to the feature manager.
```
<server>
   <featureManager>
      <feature>openapi-3.0</feature>
   </featureManager>
</server>
```
2. Optional: Specify that an application OpenAPI is private.
  
  By default, OpenAPI documentation is public. All users can access public APIs, often without authentication. Public APIs are documented in the /api/docs resource.
  You can specify that APIs remain private. APIs for administrative use are typically kept private. Private APIs, which use passwords for protection, are documented in the /ibm/api/docs resource. This resource documents all private APIs and all public APIs.
  
  You can specify private APIs for web applications in two ways:
  - Use webModuleDoc in the server configuration, with the public attribute set to false.
    1. Add an openapi element and set its enablePrivateURL Boolean attribute to true.
    2. Add a webModuleDoc subelement for each web application and sets its public Boolean attribute to true for public APIs and to false for private APIs.
    The following example makes the airlines application OpenAPIs visible, and disables exposure of the airlinesAdmin application OpenAPIs.
```
<openapi enablePrivateURL="true">
  <webModuleDoc contextRoot="/airlines" public="true" />
  <webModuleDoc contextRoot="/airlinesAdmin" public="false" />
</openapi>
```
    By default, the public attribute of webModuleDoc is set to true. This configuration is needed only to disable applications that you want to keep private.
  - Use a vendor extension keyword in the API description to designate that an API is private.
    1. Add an openapi element to the server configuration and set its enablePrivateURL Boolean attribute to true.
    2. Put the x-ibm-private: true keyword and value in the API description document META-INF/openapi.yaml file, or in the file of another supported format. This value overrides the default visibility of the API and this value can be overridden by a webModuleDoc entry.
3. Optional: Specify that an application not appear in the OpenAPI document.
  
  By default, your web modules that contain REST API documents appear in the merged OpenAPI document available in the /api/docs resource. To keep web modules from appearing in the OpenAPI document, change the attributes of the webModuleDoc element in the server configuration.
  Identify the web module that you want to hide or display with the contextRoot attribute. Then, change the enabled attribute to false to hide the web module from the OpenAPI document. The default value for the enabled attribute is true. In the following example, the airlines module is configured so that it appears in the OpenAPI document while the airlinesAdmin module is hidden.
```
<openapi>
  <webModuleDoc contextRoot="/airlines" enabled="true" />
  <webModuleDoc contextRoot="/airlinesAdmin" enabled="false" />
</openapi>
```
  Note: The enabled attribute is not supported for REST API documents that are supplied by other Liberty features.
Optional: Enable JAX-RS annotation scanning.

Add the jaxrs-2.0 feature to the feature manager. When both the jaxrs-2.0 and openapi-3.0 features are enabled in a server, the annotation scanner scans all web applications that are deployed on the server unless the server configuration disables the scanning. The scanner goes through classes that are annotated with the OpenAPI 3.0 annotations on class definition and annotated with the @Path JAX-RS annotation. You can access generated OpenAPI documents with the OpenAPI public endpoint (api/docs) and the private endpoint (ibm/api/docs).
Allow third-party API visibility for specific applications.
To enable runtime loading of OpenAPI annotations, model, and programming models, you must enable third-party API visibility for the specific application.
1. Define the apiTypeVisibility attribute of the classloader element as third-party API visibility. Add third-party to the classloader element in your server.xml file.
  
  If you do not specify classloader to include third-party in apiTypeVisibility, it uses the default definition of spec, stable, and ibm-api.
```
<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
  <classloader apiTypeVisibility="spec, ibm-api, stable, third-party" commonLibraryRef="Alexandria" />
</application>
```
Optional: Enable validation of OpenAPI documents.

The validation capability is disabled by default. When you enable validation, each OpenAPI document that is provided by the application is validated against the constraints declared in the OpenAPI V3 specification by the openapi-3.0 feature. If openapi-3.0 finds an OpenAPI document that is not valid, the feature reports an error in the logs for each violated constraint. The invalid document is excluded from the aggregated OpenAPI document that is returned by the api/docs endpoint. To enable validation, set the validation attribute to true in the server.xml file.
```
<openapi validation="true"/>
```
Deploy your applications.
View the generated API document in a browser.
You can find your generated API document at the /api/docs endpoint by using one of the following URLs, depending on whether your API is public or private.
- For non-SSL public APIs, view your document at http://Liberty_host:http_port/api/docs.
- For SSL public APIs, view your document at https://Liberty_host:https_port/api/docs.
- For SSL private APIs, view your document at https://Liberty_host:https_port/ibm/api/docs.
Tip: By default, two endpoints are available for a server.
- GET http://Liberty_host:http_port/api/docs
- GET http://Liberty_host:http_port/api/explorer
You can customize URLs for public endpoints with the publicURL attribute in the server.xml file. The following example illustrates the configuration in the server.xml file to make the public REST API documentation available with GET http://Liberty_host:http_port/myAPI/docs and http://Liberty_host:http_port/myAPI/explorer.
```
<openapi publicURL="myAPI" />
```
The OpenAPI document is generated and aggregated across applications for that Liberty server. The document is in YAML format by default. When you view your documentation with Microsoft Internet Explorer 11, it returns a YAML document that is not properly formatted. As a workaround, use a browser such as Mozilla Firefox or Google Chrome browser. If the http request has an Accept header with an application/json value, the document is in JSON format.

Tip: You can filter the OpenAPI document by context root. Both the public endpoint (api/docs) and the private endpoint (ibm/api/docs) support a query parameter, root, that can filter the found context roots. For example, a call to GET http://Liberty_host:http_port/api/docs?root=/myApp retrieves an OpenAPI V3 document that has only the documentation for the myApp context root.

Results

The OpenAPI User Interface renders the aggregated definitions from /api/docs to display a human-friendly UI at http://Liberty_host:http_port/api/explorer. If you enable SSL, you can access the protected UI at https://Liberty_host:https_port/api/explorer.

You can browse the private web modules by enabling the enablePrivateURL attribute in the openAPI element of the server.xml file.

<openapi enablePrivateURL="true"/>

When the private web module browsing is enabled, use https://Liberty_host:https_port/ibm/api/explorer to display the human-friendly UI for both public and private web modules.

You can view all RESTful endpoints from your application in this user interface. You can also filter displayed endpoints to focus on specific applications.