An amazing article Developing a Swagger-enabled REST API using WebSphere Developer Tools demonstrates how to expose a usual servlet as a REST API using a new feature of WebSphere Liberty called apiDiscovery-1.0.
I've rewritten a bit the code of the servlet taking the JSR 353/JSON-P API into account and eliminated all WebSphere-related code, so the demonstration project can be built using Apache Maven: just put the 'javax.json:javax.json-api:jar' dependency into your pom.xml.
Including a swagger.json or swagger.yaml file inside the corresponding META-INF folder is the easiest way to expose the documentation of web modules, but not the only one. If the web application does not provide a swagger.json or swagger.yaml file and the application contains JAX-RS annotated resources, the Swagger document would be automatically generated. As mentioned in the official documentation, the server configuration must have the apiDiscovery-1.0 feature and the jaxrs-1.1 or jaxrs-2.0 feature; for example:
The product scans all classes in the web application for JAX-RS and Swagger annotations, searching for classes with @Path, @Api, and @SwaggerDefinition annotations. The apiDiscovery-1.0 feature automatically generates a corresponding Swagger document and makes it available at the following URIs: http://host:port/context-root/swagger.json and http://host:port/context-root/swagger.yaml.
For example, if the following JAX-RS resource is deployed on the server:
The application server generates the corresponding swagger.json (see the Gist on GitHub) and you should see a rendering of the API:
Rich REST APIs are being leveraged everywhere in the world because they are language-neutral and can be easy used from a server, single-page web application, as well as mobile- or Internet-of-things device. It's a good news for IBM customers, the corporation has added the support of REST APIs as well as Swagger, the world’s largest framework of API developer tools, to IBM's modern products such as WebSphere Liberty and Integration Bus.
Would you like to give a 'Like'? Please follow me on Twitter!
I've rewritten a bit the code of the servlet taking the JSR 353/JSON-P API into account and eliminated all WebSphere-related code, so the demonstration project can be built using Apache Maven: just put the 'javax.json:javax.json-api:jar' dependency into your pom.xml.
Including a swagger.json or swagger.yaml file inside the corresponding META-INF folder is the easiest way to expose the documentation of web modules, but not the only one. If the web application does not provide a swagger.json or swagger.yaml file and the application contains JAX-RS annotated resources, the Swagger document would be automatically generated. As mentioned in the official documentation, the server configuration must have the apiDiscovery-1.0 feature and the jaxrs-1.1 or jaxrs-2.0 feature; for example:
The product scans all classes in the web application for JAX-RS and Swagger annotations, searching for classes with @Path, @Api, and @SwaggerDefinition annotations. The apiDiscovery-1.0 feature automatically generates a corresponding Swagger document and makes it available at the following URIs: http://host:port/context-root/swagger.json and http://host:port/context-root/swagger.yaml.
For example, if the following JAX-RS resource is deployed on the server:
The application server generates the corresponding swagger.json (see the Gist on GitHub) and you should see a rendering of the API:
* * *
Rich REST APIs are being leveraged everywhere in the world because they are language-neutral and can be easy used from a server, single-page web application, as well as mobile- or Internet-of-things device. It's a good news for IBM customers, the corporation has added the support of REST APIs as well as Swagger, the world’s largest framework of API developer tools, to IBM's modern products such as WebSphere Liberty and Integration Bus.
Would you like to give a 'Like'? Please follow me on Twitter!
No comments:
Post a Comment