Swagger is a RESTful API Documentation Specification that describes and documents Application Programming Interfaces (API). From the swagger.io site documentation:
The Swagger specification defines a set of files required to describe such an API. These files can then be used by the Swagger-UI project to display the API and Swagger-Codegen to generate clients in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools.
The Issuetrak API employs technology to produce a “Swagger” API portal dashboard that is accessible from a
specific URL relative to the API installation path, which is discussed in the sections below.
This Swagger dashboard displays baseline API documentation for each of the Issuetrak API operation endpoints including:
- API Operation Endpoint URLs
- API Operation Implementation Notes
- API Operation Request Schema
- API Operation Response Schema
- API Operation Response Codes
In addition, the Swagger dashboard provides the ability to issue test API requests using a request schema builder tool and to observe the API response for such test requests.
Swagger Access Controls
You should know that access to your site's Swagger page is determined by settings in the API site's web.config file. You can find this in: {IssuetrakWebFolderPath}\API
The two settings in the API web.config that control access to the Swagger page are discussed below. The Issuetrak IDM sets the values for these settings during the initial site/API deployment, but you can change them using a text editor later.
APIAuthorizationBypassReferrers
The value expressed in this setting should match the URL of the API website. The URL must end with /api/swagger/ui/index
<value>http://www.mysite.com/api/swagger/ui/index</value>
APIAuthorizationBypassIPAddresses
The value expressed in this setting should include the IP addresses of any computers that should be allowed to connect to the Swagger UI for the Issuetrak API. If more than one IP address is included in the list, then each value should be separated with a comma only (without spaces).
<value>1.2.3.4,5.6.7.8</value>
How to Access the Swagger Dashboard
Steps:
- Determine the base URL that maps to the full virtual path for the Issuetrak API installation to access.
An example of the base API URL for an installation is: https://localhost/api/
- Append “/swagger” to the base URL obtained in the previous step. Open this augmented URL with a web browser.
An example of the the augmented API URL to access the Swagger dashboard is: https://localhost/api/swagger/
