Documenting your API using Swagger

When you have created your API, you can expose the API documentation to users.

zosConnect-2.0 Applies to zosConnect-2.0.

You can provide this documentation with Swagger. For more information, see A launch icon to indicate a link opens a new tab or window. Introduction to Swagger. For details in the Swagger specification, see Swagger RESTful API Documentation Specification.

A RESTful administration interface for an API is available on the URI /<apiBasePath>/api-docs and returns the Swagger document for the API, which is typically generated using the IBM® z/OS® Connect tooling.

Alternatively, you can use the API discovery feature to see the generated swagger documentation for any APIs deployed to the IBM z/OS Connect server. The interfaces for these APIs are available on the URI /api/docs?root=/<apiBasePath>. For more information about this feature, see A launch icon to indicate a link opens a new tab or window. Discovering REST API documentation on a Liberty server in the WebSphere Application Server Liberty documentation.

API Swagger documents are only returned if the API has been correctly initialized:

HTTP method: GET
URI: /<apiBasePath>/api-docs
Note: The only allowed methods for this URI are GET and OPTIONS.; /api/docs?root=/<apiBasePath>
Return body: Returns the Swagger document as a JSON string with an HTTP status code of 200 OK.
The host and port values are added to the returned Swagger document, and override a host entry specified in the Swagger document on disk. The host name and port are derived from the request string.
Errors: For any call using a HTTP method other than GET and OPTIONS, a HTTP status code of 405 Method Not Allowed is returned.; If the <apiBasePath> does not exist or cannot be accessed, a HTTP status code of 404 Not Found is returned.

For more information, see A launch icon to indicate a link opens a new tab or window. Swagger RESTful API Documentation Specification.