![[9.0.0.1 or later]](../images/ng9001.gif)
Discovering REST API documentation
Starting with WebSphere® Application Server traditional 9.0.0.1, you can discover and expose Swagger documentation for your deployed RESTful endpoints. You can also use the built-in Swagger user interface to invoke the APIs.
About this task
Discover Swagger documentation for your deployed RESTful endpoints and use the interface to invoke APIs.
Procedure
- If you use a custom profile in a deployment manager environment, install and map Swagger
applications to application servers that are running on custom profiles. Skip this step if you use
an application server profile, or something other than a deployment manager environment.
- Run the deploySwaggerUI script to install Swagger applications onto a
target.
- Change user_name and user_password to the appropriate values.
A target must be the last parameter and enclosed by single quotation marks. See the following
example invocation of the deploySwaggerUI script:
wsadmin -user user_name -password user_password -f deploySwaggerUI.py install 'WebSphere:cell=cell01,node=node01,server=server1'
- Run the following wsadmin commands to map the applications to additional target servers:
AdminApp.edit('SwaggerUI', '[ -MapModulesToServers [[ SwaggerUI SwaggerUI.war,WEB-INF/web.xml WebSphere:cell=cell01,node=node01,server=server1+WebSphere:cell=cell01,node=node02,server=server1 ]]]') AdminApp.edit('RESTAPIDocs', '[ -MapModulesToServers [[ RESTAPIDocs RESTAPIDocs.war,WEB-INF/web.xml WebSphere:cell=cell01,node=node01,server=server1+WebSphere:cell=cell01,node=node02,server=server1 ]]]') AdminConfig.save()
- Change user_name and user_password to the appropriate values.
A target must be the last parameter and enclosed by single quotation marks. See the following
example invocation of the deploySwaggerUI script:
- Optional: If you no longer want to enable API discovery, remove the two applications from the cell.
wsadmin -user user_name -password <ADMIN_USER_PASS -f deploySwaggerUI.py remove
- Run the deploySwaggerUI script to install Swagger applications onto a
target.
- Enable the API discovery service with the administrative console or the wsadmin
AdminConfig.modify command.
- Use the administrative console to enable the API discovery service.
- Click Servers > Server Types > WebSphere application servers > server_name > Web Container Settings > Web container.
- Select Enable API discovery service.
- Save your changes and restart the server for the changes to take effect.
For more information, see Web container settings.
- Use wsadmin scripting to enable the API discovery service.
- Run the AdminConfig.modify command. Replace ${CELL},
${NODE} and ${SERVER} with the appropriate
values.
AdminConfig.modify('(cells/${CELL}/nodes/${NODE}/servers/${SERVER}|server.xml #WebContainer_1183122130078)', '[ [apiDiscovery "true"] ]')
- Restart the server for the changes to take effect.
For more information, see Commands for the AdminConfig object using wsadmin scripting.
- Run the AdminConfig.modify command. Replace ${CELL},
${NODE} and ${SERVER} with the appropriate
values.
- Use the administrative console to enable the API discovery service.
- Document RESTful endpoints.
Best practice: Use the Swagger annotations to augment your existing JAX-RS endpoints. If you have JAX-RS (1.1 or 2.0) applications installed, you can skip this step, but the Swagger annotations allows you to add more detail to each endpoint. For Swagger annotations, see Package io.swagger.annotations.bprac
- To use and compile the Swagger annotations, add the
app_server_root/dev/swagger/swagger-annotations-1.5.3.jar to
your classpath.
WebSphere Developer Tools automatically adds the directory to your filepath.
- Add a generated swagger.json or swagger.yaml
file.
- For servlets, include a generated swagger.json or swagger.yaml file inside the META-INF folder of your web module.
- For hybrid web modules that contain both JAX-RS and servlets, include a generated
swagger.json or swagger.yaml inside the
META-INF/stub folder of your web module, which is merged with the annotations
processed in the JAX-RS portion.If your application is using a different virtual host than the default_host, or if you want to document a load-balancer in your API, include a minimal swagger.json or swagger.yaml inside the META-INF/stub folder of your web module that includes the new host:port. See the following example:
{ "swagger": "2.0", "host": "virtualHost:3005" }
Restriction: You can expose J2EE applications (EAR, WAR), but you cannot expose OSGi applications (EBA).
- To use and compile the Swagger annotations, add the
app_server_root/dev/swagger/swagger-annotations-1.5.3.jar to
your classpath.
- View generated documentation and the user interface explorer.
- Aggregated the Swagger document
- Open your browser and navigate to https://host:https_port/ibm/api/docs to receive a Swagger 2.0 document in JSON format, which contains the aggregated documentation of your RESTful endpoints.
- Add Accept with a value of application/yaml to the request header to receive this document in YAML format.
- Use the multiple-cardinality query parameter root to filter the endpoint. For example, call /ibm/api/docs?root=/airlines to receive a Swagger document that only contains information about the endpoints from the /airlines web module.
- Swagger UI explorer
- Open your browser and navigate to https://host:https_port/ibm/api/explore.
- Call /ibm/api/docs to receive the user interface. Click Try it out to navigate through and invoke the various endpoints.
- Aggregated the Swagger document


File name: t_rest_api_disc_doc.html