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.
Before you begin
Learn about the OpenAPI V3 specification. You use YAML or JSON files to
document the RESTful APIs in your applications.
About this task
You can explore these features, such as the new user interface, annotations, and programming
interfaces, with the following sample applications.
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.
- Add the openapi-3.0 feature to the feature manager.
<server>
<featureManager>
<feature>openapi-3.0</feature>
</featureManager>
</server>
- 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.
- Add an openapi element and set its enablePrivateURL Boolean
attribute to true.
- 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.
- Add an openapi element to the server configuration and set its
enablePrivateURL Boolean attribute to true.
- 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.
- 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.
- 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 and
ibm-api.
<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
<classloader apiTypeVisibility="spec, ibm-api, third-party" commonLibraryRef="Alexandria" />
</application>
- Optional: Enable validation of OpenAPI documents.
The validation capability is unavailable 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.