¶ 1. Overview.
Swagger is a tool that makes it easier to create, document, and consume APIs (Application Programming Interface). It provides an interactive interface that allows developers and external consumers to view, test, and interact with an API's endpoints in an intuitive way. Through Swagger, it is possible to automatically generate API documentation from the source code, ensuring the documentation is always up to date and synchronized with the implementations. In addition, Swagger supports a wide range of programming languages and frameworks.
¶ 2. Authentication and Authorization.
By default, Swagger is only accessible in the development environment. For production environments, enabling it is optional through configuration.
Behavior
| Environment | SwaggerEnabled Parameter | Authenticated User | Result |
|---|---|---|---|
| Development | N/A | Yes | ✓ Access granted |
| Development | N/A | No | 401 Unauthorized |
| Production | false (default) | Yes/No | 403 Forbidden |
| Production | true | Yes | ✓ Access granted |
| Production | true | No | 401 Unauthorized |
- Returns 403 (Forbidden) when Swagger is disabled for the environment.
- Returns 401 (Unauthorized) when the user is not authenticated.
How to enable in production
Include this setting in the appsettings.json file:
{
"SwaggerEnabled": true
}
- In production environments, the default is false.
There are several authentication methods available in Swagger. The most commonly used are:
- Basic: Authorization using username and password, separated by ":" and converted into Base64;
- Bearer: A Schema that uses a JWT (JSON Web Token) token, which authorizes the user to access the APIs;
- OAuth 2: An authorization protocol via Token;
¶ 3. Usage.
To open Swagger, use the endpoint: URL.../swagger/index.html
- Example of an endpoint in a cloud environment:
qablue.tech6cloud.com/swagger/index.html; (in this case, qablue is your domain name.) - Example of an endpoint in a local environment:
(IIS server)/(application name in IIS)/swagger/index.html
The URL provided before the API depends on your cloud domain or, in a local environment, on the settings configured in your IIS (Internet Information Services).
When you access the endpoint, a page containing all system APIs will open. Click 
to expand the selected API.
- The parameters required to execute the API will be displayed, along with the possible responses the system may return, as well as a detailed request view. To enable parameter input and run the API, click "Try it out"
- When you click "Try it out", parameter input is enabled, and the "Execute" button is displayed, which runs the API according to the entered parameters
- When executing the API, Swagger returns a response with the code and description, indicating whether execution succeeded or failed. In case of failure, it returns the error code and reason in detail
For more information and ways to consume APIs, visit our help center: Data Integration
¶ 4. Q&A
Frequently Asked Questions
1. How do I access Swagger in a production environment?
To access Swagger in a production environment, you need to enable the configuration in the appsettings.json file by setting "SwaggerEnabled": true. By default, Swagger is disabled in production for security reasons.
2. Why do I receive a 403 (Forbidden) error when trying to access Swagger?
The 403 (Forbidden) error indicates that Swagger is disabled for the current environment. In production environments, Swagger needs to be explicitly enabled through the "SwaggerEnabled": true configuration in the appsettings.json file.
3. Why do I receive a 401 (Unauthorized) error when accessing Swagger?
The 401 (Unauthorized) error means you are not authenticated in the system. You need to log in to the application before accessing Swagger, regardless of the environment (development or production).
4. What authentication methods are available in Swagger?
Swagger supports three main authentication methods:
- Basic: Uses username and password separated by ":" and converted to Base64.
- Bearer: Uses a JWT (JSON Web Token) token for authorization.
- OAuth 2: Authorization protocol via Token.
5. How do I execute an API through Swagger?
To execute an API in Swagger:
- Click on the desired API to expand it.
- Click the "Try it out" button.
- Fill in the required parameters.
- Click the "Execute" button.
- View the response returned by the system.
6. What is the default URL to access Swagger?
The default URL follows the format: URL.../swagger/index.html. In a cloud environment, it would be something like yourdomain.tech6cloud.com/swagger/index.html. In a local environment, it depends on the IIS configuration: (IIS server)/(application name in IIS)/swagger/index.html.
7. What does the response Swagger returns after executing an API mean?
Swagger's response includes an HTTP status code and a description. 2xx codes indicate success, while 4xx or 5xx codes indicate errors. In case of failure, Swagger provides details about the error code and the reason for the failure.
8. Is Swagger documentation updated automatically?
Yes, Swagger automatically generates API documentation from the source code, ensuring that the documentation is always up to date and synchronized with the implementations.
9. Is it safe to leave Swagger enabled in production?
Swagger exposes information about your API's structure and endpoints. For security reasons, it is disabled by default in production. Enable it only if there is a specific need and ensure that only authenticated users can access it.
10. Can I test all system APIs through Swagger?
Yes, Swagger displays all available APIs in the system, allowing you to view, test, and interact with each endpoint interactively. It is a comprehensive tool for developers and external consumers to test API functionalities.