Discover REST API documentation

Starting with WebSphere Application Server traditional 9.0.0.1, we can discover and expose Swagger documentation for our deployed RESTful endpoints. We can also use the built-in Swagger user interface to invoke the APIs.

Discover Swagger documentation for our deployed RESTful endpoints and use the interface to invoke APIs.

Tasks

1. If we use a custom profile in a deployment manager environment, install and map Swagger applications to application servers running on custom profiles.

   Skip this step if we use an application server profile, or something other than a deployment manager environment.

   1. Run the deploySwaggerUI script to install Swagger applications onto a target.

      1. 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'
         

      2. 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()

   2. Optional: If we 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 
      

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

     1. Click Servers > Server Types > WebSphere application servers > server > Web Container Settings > Web container.

     2. Select Enable API discovery service.

     3. Save changes and restart the server for the changes to take effect.

     

     See Web container settings.

   • Use wsadmin scripting to enable the API discovery service.

     1. 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"] ]')
        

     2. Restart the server for the changes to take effect.

     See Commands for the AdminConfig object.

3. Document RESTful endpoints.

   Use the Swagger annotations to augment our existing JAX-RS endpoints. If we have JAX-RS (1.1 or 2.0) applications installed, we can skip this step, but the Swagger annotations allows us to add more detail to each endpoint. For Swagger annotations, see Package io.swagger.annotations.bprac

   1. To use and compile the Swagger annotations, add the app_server_root/dev/swagger/swagger-annotations-1.5.3.jar to the classpath.

      WebSphere Developer Tools automatically adds the directory to the filepath.

   2. 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 our 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 our web module, which is merged with the annotations processed in the JAX-RS portion.

        If the application is using a different virtual host than the default_host, or to document a load-balancer in your API, include a minimal swagger.json or swagger.yaml inside the META-INF/stub folder of our web module that includes the new host:port. See the following example:

        {
        "swagger": "2.0",
        "host": "virtualHost:3005"
        }
        

   Restriction: We can expose J2EE applications (EAR, WAR), but we cannot expose OSGi applications (EBA).

4. View generated documentation and the user interface explorer.
   1. Aggregated the Swagger document

      1. 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 our RESTful endpoints.

      2. Add Accept with a value of application/yaml to the request header to receive this document in YAML format.

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

   2. Swagger UI explorer

      1. Open your browser and navigate to https://host:https_port/ibm/api/explore.
      2. Call /ibm/api/docs to receive the user interface. Click Try it out to navigate through and invoke the various endpoints.