API - Swagger Overview

Swagger Overview

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 1.

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.

For example, if an API installation uses the following URL to access the Issuetrak API:

https://localhost/api/

then the API dashboard will be accessible via:

https://localhost/api/swagger/

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 2.

Steps to Access the Swagger Dashboard

1

Determine the base URL that maps to the full virtual path for the Issuetrak API installation to access. Please refer to the “Web Server Installation” section within the API documentation for further details.

An example of the base API URL for an installation is:

https://localhost/api/

2

To the base URL obtained in Step (1), append “/swagger”. 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/


1 “Swagger Specification”: http://swagger.io/specification/
2 Please note that to employ the Swagger dashboard testing tool, the Issuetrak API installation’s configuration file must be properly configured with the correct “APIAuthorizationBypassReferrers” and “APIAuthorizationBypassIPAddresses” settings. Please refer to the Issuetrak API installation article’s “Web Server Installation” section for more details.