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.

1. 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.
   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 double 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 you no longer want to enable API discovery, remove the two applications from the cell.

      wsadmin -user user_name -password user_password -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_name > Web Container Settings > Web container.
     2. Select Enable API discovery service.
     3. 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.
     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.

     For more information, see Commands for the AdminConfig object using wsadmin scripting.

3. 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 allow you to add more detail to each endpoint. For Swagger annotations, see Package io.swagger.annotations.
   1. 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.

   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 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 that are 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 Java EE applications such as EAR or WAR, but you cannot expose OSGi applications (EBA).
4. View generated documentation and the user interface explorer.
   • Aggregated Swagger document
     1. Open your browser and navigate to https://host:https_port/ibm/api/explorer to receive a Swagger 2.0 document in JSON format, which contains the aggregated documentation of your 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.
   • Swagger UI explorer
     1. Open your browser and navigate to https://host:https_port/ibm/api/explorer.
     2. Call /ibm/api/docs to receive the user interface. Click Try it out to navigate through and invoke the various endpoints.