Accessing and using Swagger UI
Swagger UI is an interface that enables developers to describe REST APIs expressed in JSON. beqom uses Swagger to document its APIs and help administrator users to consume those APIs in the proper manner.
This article describes the method to access Swagger UI, including the authorizations required, as well as the practical means to use the platform.
Getting the Authorization to Access Swagger UI
Getting the Authorization to Access Swagger UI
User-specific, service-level authorization to access Swagger UI must be defined in the k_users_parameter table of the tenant database, using the enableSwaggerAccess column.
This column has a default value of false (unauthorized). To authorize a user, the column value must be set to true.
When permission is not granted in this column, any user attempting to access the Swagger UI will return a 403 error.
Automatic configuration of this column is governed by the following rules:
When migrating an existing tenant, the column value will be set to true only for super admin users. Access to Swagger UI will be restricted for all other existing users
When creating a new user, the value of the enableSwaggerAccess column is automatically set to false, even if the new user is marked as a super admin
All requests to */swagger/* URL path require a valid token to authorize the user. The token is contained in the nextSession cookie, that needs to be set beforehand by beqom Passport.
Swagger Cookie
Swagger Cookie
An HTTPOnly, domain-based cookie, named SwaggerCookie is used to manage user-based access to Swagger UI. The presence of this cookie for a given user is governed by the following rules:
The token is generated only if the user has been granted access to Swagger in k_users_parameter
The token contains three claims of the active JWT token (aud, unique_name and auth_time)
The Swagger access validation works as follows: if the user has a Swagger token with three claims that correspond to the JWT claims, the user can access Swagger UI. Otherwise, the system blocks the user.
Access Errors
Access Errors
If a user is not properly authorized, all URL requests will return a 403 HTTP error. Users will get an error if:
The user does not have a nextSession cookie
There is no token for CloudServiceID in the nextSession cookie
The token in the nextSession cookie is not valid
Accessing Swagger UI for a Cloud Service from the beqom Application
Accessing Swagger UI for a Cloud Service from the beqom Application
URL Expression
URL Expression
From version 9.2 of the beqom application, the URL expression is standardized as follows:
https://[ClientName]-[Region]-[ApplicationStackName]-[Boundary]-[Service].beqom.com
Here is an example of URL that follows this naming convention:
https://bqm-weu-v10qa1-npr-app.beqom.com/
In order to access Swagger UI from the beqom application, you need to manually enter a path in the URL. With the standardized convention, you need to replace the name of the service (5th element of the URL) with the name of the service for which you want to access Swagger UI, and then specify that you want to use Swagger.
Using the example above, if we want to access the documentation for the Gateway service, the path to Swagger UI would then be:
https://bqm-weu-v10qa1-npr-gateway.beqom.com/swagger/index.html
Cloud Services Documented Using Swagger UI
Cloud Services Documented Using Swagger UI
Swagger UI is available for the following cloud services in the beqom application:
Gateway (example: https://bqm-weu-v10qa1-npr-gateway.beqom.com/swagger/index.html)
Data (example: https://bqm-weu-v10qa1-npr-data.beqom.com/swagger/index.html)
Object (example: https://bqm-weu-v10qa1-npr-object.beqom.com/swagger/index.html)
Environment Manager (example: https://bqm-weu-v10qa1-npr-environment-manager.beqom.com/swagger/index.html)
File (example: https://bqm-weu-v10qa1-npr-file.beqom.com/swagger/index.html)
Individual planner (example: https://bqm-weu-v10qa1-npr-compensation-planner.beqom.com/swagger/index.html)
Analytics (example: https://bqm-weu-v10qa1-npr-analytics.beqom.com/swagger/index.html)
This is an attention message.
For information about your specific app stack (if the URL does not follow the described convention), please contact beqom.
Troubleshooting
Troubleshooting
The following table lists the problems you can encounter when using Swagger and offers you potential solutions.
| Issue | Resolution |
|---|---|
| Cannot access Swagger by editing the URL as described |
|
For more information about the use of Swagger, refer to the Swagger documentation, available here.