Swagger and the REST API documentation

Swagger is a set of libraries that allows developers of a REST-based service to provide documentation and testing tools to client-side developers in an automated way. The endpoints offered by the REST API can be viewed on their own page. However, they are also documented in a more structured way using the Swagger specification language, which is embedded in the system itself.

The swagger.json file

The Swagger specification of the REST API consists of a file of JSON data called swagger.json. This schema file includes endpoint URLs, descriptions, request parameters and response structures for the entire API. Defining the endpoints in this standard, machine-readable format enables the use of automated tools such as interactive documentation and client code generation.

The Swagger schema file can be found at:

https://<serverName>:<portNumber>/bca-networks/api/swagger.json

This file is not protected by authentication and can be viewed in a browser.

The Swagger UI

One example of a tool that consumes a Swagger specification is the Swagger UI. This shows a list of endpoints in a web page, enabling users to read about them and, after authentication, submit requests. You can access the Swagger UI at:

https://<serverName>:<portNumber>/bca-networks/apidocs

The Swagger UI loads the swagger.json file and then generates web pages for viewing the contents of the API and trying out requests.

Swagger UI limitations

Swagger UI has the following limitations:

• It cannot show object inheritance. Therefore in the jobs and predefined jobs areas, the ActionDTO object cannot show you its numerous subclasses. That information is provided in the Object Definitions section, instead of in the Swagger UI.
• It cannot provide information about third-party data structures in response or request bodies. Therefore, there is no information about the JsonPatch object's contents in the Model or Example Value areas. That information is provided in the Object Definitions section, instead of in the Swagger UI.
• It does not support dynamic query parameters. Therefore, you cannot enter request parameters to filter or sort by dynamic fields.