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 Opens in new window. Introduction to Swagger. For details in the Swagger specification, see Opens in new window. 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 Opens in new 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 Opens in new window. Swagger RESTful API Documentation Specification.