|
Note
|
This repository contains the guide documentation source. To view the guide in published form, view it on the Open Liberty website. |
Explore how to document and filter RESTful APIs from code or static files by using MicroProfile OpenAPI.
You will learn how to document and filter RESTful APIs from annotations, POJOs, and static OpenAPI files by using MicroProfile OpenAPI.
The OpenAPI specification, previously known as the Swagger specification, defines a standard interface for documenting and exposing RESTful APIs. This specification allows both humans and computers to understand or process the functionalities of services without requiring direct access to underlying source code or documentation. The MicroProfile OpenAPI specification provides a set of Java interfaces and programming models that allow Java developers to natively produce OpenAPI v3 documents from their JAX-RS applications.
You will document the RESTful APIs of the provided inventory service, which serves two endpoints, inventory/systems and inventory/properties. These two endpoints function the same way as in the other MicroProfile guides.
Before you proceed, note that the 1.0 version of the MicroProfile OpenAPI specification does not define how the /openapi endpoint may be partitioned in the event of multiple JAX-RS applications running on the same server. In other words, you must stick to one JAX-RS application per server instance as the behaviour for handling multiple applications is currently undefined.
Next, point your browser to the http://localhost:9080/openapi URL and you’ll see the RESTful APIs of the inventory service. You can also point to the http://localhost:9080/openapi/ui URL for a more interactive view of the deployed APIs. This UI is built from the Open Source Swagger UI and renders the generated /openapi document into a very user friendly page.
You can generate an OpenAPI document in various ways. First, because all Jakarta Restful Web Services annotations are processed by default, you can augment your existing Jakarta Restful Web Services annotations with OpenAPI annotations to enrich your APIs with a minimal amount of work. Second, you can use a set of predefined models to manually create all elements of the OpenAPI tree. Finally, you can filter various elements of the OpenAPI tree, changing them to your liking or removing them entirely.
Navigate to the start directory to begin.
Because the Jakarta Restful Web Services framework handles basic API generation for Jakarta Restful Web Services annotations, a skeleton OpenAPI tree will be generated from the inventory service. You can use this tree as a starting point and augment it with annotations and code to produce a complete OpenAPI document.
Now, visit the http://localhost:9080/openapi URL to see the generated OpenAPI tree. You can also visit the http://localhost:9080/openapi/ui URL for a more interactive view of the APIs.
Because all Jakarta Restful Web Services annotations are processed by default, you can augment the existing code with OpenAPI annotations without needing to rewrite portions of the OpenAPI document that are already covered by the Jakarta Restful Web Services framework.
Replace theInventoryResourceclass.src/main/java/io/openliberty/guides/inventory/InventoryResource.java
Add OpenAPI @APIResponse, @APIResponseSchema, @Operation, and @Parameter annotations to the two JAX-RS endpoint methods, getPropertiesForHost() and listContents().
InventoryResource.java
link:finish/src/main/java/io/openliberty/guides/inventory/InventoryResource.java[role=include]Clearly, there are many more OpenAPI annotations now, so let’s break them down:
| Annotation | Description |
|---|---|
|
Describes a single response from an API operation. |
|
Convenient short-hand way to specify a simple response with a Java class that could otherwise be specified using @APIResponse. |
|
Describes a single API operation on a path. |
|
Describes a single operation parameter. |
Because the Open Liberty instance was started in dev mode at the beginning of the guide, your changes were automatically picked up. Refresh the http://localhost:9080/openapi URL to see the updated OpenAPI tree. The two endpoints at which your JAX-RS endpoint methods are served are now more meaningful:
/inventory/systems:
get:
summary: List inventory contents.
description: Returns the currently stored host:properties pairs in the inventory.
responses:
"200":
description: host:properties pairs stored in the inventory.
content:
application/json:
schema:
$ref: '#/components/schemas/InventoryList'
/inventory/systems/{hostname}:
get:
summary: Get JVM system properties for particular host
description: Retrieves and returns the JVM system properties from the system
service running on the particular host.
parameters:
- name: hostname
in: path
description: The host for whom to retrieve the JVM system properties for.
required: true
schema:
type: string
example: foo
responses:
"404":
description: Missing description
content:
application/json: {}
"200":
description: JVM system properties of a particular host.
content:
application/json:
schema:
type: objectOpenAPI annotations can also be added to POJOs to describe what they represent. Currently, your OpenAPI document doesn’t have a very meaningful description of the InventoryList POJO and hence it’s very difficult to tell exactly what that POJO is used for. To describe the InventoryList POJO in more detail, augment the src/main/java/io/openliberty/guides/inventory/model/InventoryList.java file with some OpenAPI annotations.
Replace theInventoryListclass.src/main/java/io/openliberty/guides/inventory/model/InventoryList.java
Add OpenAPI @Schema annotations to the InventoryList class and the systems variable.
InventoryList.java
link:finish/src/main/java/io/openliberty/guides/inventory/model/InventoryList.java[role=include]Likewise, annotate the src/main/java/io/openliberty/guides/inventory/model/SystemData.java POJO, which is referenced in the InventoryList class.
Replace theSystemDataclass.src/main/java/io/openliberty/guides/inventory/model/SystemData.java
Add OpenAPI @Schema annotations to the SystemData class, the hostname variable and the properties variable.
SystemData.java
link:finish/src/main/java/io/openliberty/guides/inventory/model/SystemData.java[role=include]Refresh the http://localhost:9080/openapi URL to see the updated OpenAPI tree:
components:
schemas:
InventoryList:
description: POJO that represents the inventory contents.
required:
- systems
type: object
properties:
systems:
type: array
items:
$ref: '#/components/schemas/SystemData'
total:
format: int32
type: integer
SystemData:
description: POJO that represents a single inventory entry.
required:
- hostname
- properties
type: object
properties:
hostname:
type: string
properties:
type: objectFiltering of certain elements and fields of the generated OpenAPI document can be done by using the OASFilter interface.
Create theInventoryOASFilterclass.src/main/java/io/openliberty/guides/inventory/filter/InventoryOASFilter.java
InventoryOASFilter.java
link:finish/src/main/java/io/openliberty/guides/inventory/filter/InventoryOASFilter.java[role=include]The filterAPIResponse() method allows filtering of APIResponse elements. When you override this method, it will be called once for every APIResponse element in the OpenAPI tree. In this case, you are matching the 404 response that is returned by the /inventory/systems/{hostname} endpoint and setting the previously missing description. To remove an APIResponse element or another filterable element, simply return null.
The filterOpenAPI() method allows filtering of the singleton OpenAPI element. Unlike other filter methods, when you override filterOpenAPI(), it is called only once as the last method for a particular filter. Hence, make sure that it doesn’t override any other filter operations that are called before it. Your current OpenAPI document doesn’t provide much information on the application itself or on what server and port it runs on. This information is usually provided in the info and servers elements, which are currently missing. Use the OASFactory class to manually set these and other elements of the OpenAPI tree from the org.eclipse.microprofile.openapi.models package. The OpenAPI element is the only element that cannot be removed, because that would mean removing the whole OpenAPI tree.
Each filtering method is called once for each corresponding element in the model tree. You can think of each method as a callback for various key OpenAPI elements.
Before you can use the filter class that you created, you need to create the microprofile-config.properties file.
Create the configuration file.
src/main/resources/META-INF/microprofile-config.properties
microprofile-config.properties
link:finish/src/main/resources/META-INF/microprofile-config.properties[role=include]This configuration file is picked up automatically by MicroProfile Config and registers your filter by passing in the fully qualified name of the filter class into the mp.openapi.filter property.
Refresh the http://localhost:9080/openapi URL to see the updated OpenAPI tree:
info:
title: Inventory App
description: App for storing JVM system properties of various hosts.
license:
name: Eclipse Public License - v 2.0
url: https://www.eclipse.org/legal/epl-2.0
version: "1.0"
servers:
- url: "http://localhost:{port}"
description: Simple Open Liberty.
variables:
port:
default: "9080"
description: Server HTTP port.responses:
"404":
description: Invalid hostname or the system service may not be running on
the particular host.
content:
application/json: {}For more information about which elements you can filter, see the MicroProfile API documentation.
To learn more about MicroProfile Config, visit the MicroProfile Config GitHub repository and try one of the MicroProfile Config guides.
As an alternative to generating the OpenAPI model tree from code, you can provide a valid pregenerated OpenAPI document to describe your APIs. This document must be named openapi with a yml, yaml, or json extension and be placed under the META-INF directory. Depending on the scenario, the document might be fully or partially complete. If the document is fully complete, then you can disable annotation scanning entirely by setting the mp.openapi.scan.disable MicroProfile Config property to true. If the document is partially complete, then you can augment it with code.
To use the pre-generated OpenAPI document, create the OpenAPI document YAML file.
Create the OpenAPI document file.
src/main/resources/META-INF/openapi.yaml
openapi.yaml
link:finish/src/main/resources/META-INF/openapi.yaml[role=include]This document is the same as your current OpenAPI document with extra APIs for the /inventory/properties endpoint. This document is complete so you can also add the mp.openapi.scan.disable property and set it to true in the src/main/resources/META-INF/microprofile-config.properties file.
Replace the configuration file.
src/main/resources/META-INF/microprofile-config.properties
Add and set the mp.openapi.scan.disable property to true.
microprofile-config.properties
link:finish/src/main/resources/META-INF/microprofile-config.properties[role=include]Refresh the http://localhost:9080/openapi URL to see the updated OpenAPI tree:
/inventory/properties:
get:
operationId: getProperties
responses:
"200":
description: JVM system properties of the host running this service.
content:
application/json:
schema:
type: object
additionalProperties:
type: stringNo automated tests are provided to verify the correctness of the generated OpenAPI document. Manually verify the document by visiting the http://localhost:9080/openapi or the http://localhost:9080/openapi/ui URL.
A few tests are included for you to test the basic functionality of the inventory service. If a test failure occurs, then you might have introduced a bug into the code. These tests will run automatically as a part of the integration test suite.
You will see the following output:
-------------------------------------------------------
T E S T S
-------------------------------------------------------
Running it.io.openliberty.guides.system.SystemEndpointIT
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.4 sec - in it.io.openliberty.guides.system.SystemEndpointIT
Running it.io.openliberty.guides.inventory.InventoryEndpointIT
[WARNING ] Interceptor for {http://client.inventory.guides.openliberty.io/}SystemClient has thrown exception, unwinding now
Could not send Message.
[err] The specified host is unknown: java.net.UnknownHostException: UnknownHostException invoking http://badhostname:9080/inventory/properties: badhostname
Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.264 sec - in it.io.openliberty.guides.inventory.InventoryEndpointIT
Results :
Tests run: 4, Failures: 0, Errors: 0, Skipped: 0The warning and error messages are expected and result from a request to a bad or an unknown hostname. This request is made in the testUnknownHost() test from the InventoryEndpointIT integration test.
You have just documented and filtered the APIs of the inventory service from both the code and a static file by using MicroProfile OpenAPI in Open Liberty.
Feel free to try one of the related MicroProfile guides. They demonstrate additional technologies that you can learn and expand on top of what you built here.
For more in-depth examples of MicroProfile OpenAPI, try one of the demo applications available in the MicroProfile OpenAPI GitHub repository.