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
.
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
,
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.