Swagger and the REST API
The swagger.json file
The Swagger specification of the REST API consists of a file of JSON data called
swagger.json. This file includes endpoint URLs, descriptions, request parameters and response structures. Defining the endpoints in this standard, machine-readable format enables the use of automated tools such as interactive documentation and client code generation.
As each version of the REST API has its own list of endpoints, there is one
swagger.json file per version. For example, the specification of the endpoints in version 1.0 of the API can be found at:
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. BMC Discovery 11.1 and later appliances host the Swagger UI and link to it from the Help menu on every page:
Alternatively you can access the Swagger UI directly at:
The Swagger UI loads the specified
swagger.json file and then displays an expandable list of endpoints, grouped by category:
Each endpoint has a Try it out! button which lets you submit a request to it. However, as with all requests to endpoints in the REST API, an authentication token must be supplied in an HTTP header. The Swagger UI automatically adds such a header to every request, once you have supplied a token. To do this, click Authorize in the top right of the Swagger UI page to display the Available Authorizations dialog:
This dialog supports tokens generated by both mechanisms described in the topic Authentication and permissions in the REST API:
- To generate an expiring token from the
/api/tokenendpoint, enter the username and password to use in the OAuth 2.0 section and click Authorize. This returns you to the main Swagger UI page, with a request to
/api/tokenoccurring in the background. If this request succeeds, the resulting token is added to every endpoint request you make. Note that after sixty minutes the token will expire and you will need to generate another token.
- To use a permanent token, first generate one from the BMC Discovery Users administration page. Then enter this token in the Api key authorization section of the Authorizations dialog above. As with setting HTTP headers directly, the value of the header field must be in the form
"bearer <your_token>". Now click Authorize to return to the main Swagger UI page. The token you entered will now be added to every endpoint request you make.
Try it out!
The Swagger UI allows you to call any endpoint in the REST API, but does not provide a sandbox for this experimentation. Some endpoints make changes to the state of the appliance - for example, creating a new discovery run or deleting a credential. Only call these endpoints from the Swagger UI if you are happy for the changes to be made on the appliance you are connected to.