Browsing and Trying OpenCatapult API with Swagger

tips-and-tricks
#1

API component is the center of OpenCatapult system. If you are OpenCatapult developers, it is essential for you to be familiar with its endpoints along with the possible payloads and responses. You don’t have to memorize them of course, but you need to know where to find the references quickly when needed.

There are many ways to get the references to the API endpoints, i.e. directly from the source code, from the docs, or from its companion swagger. The last one is my favorite because I can try it right away in one place without jumping to external tools.

Swagger (a.k.a OpenAPI) is a specification for Web API documentation. Swashbuckle.AspNetCore is an open source project for generating Swagger documents for ASP.NET Core Web APIs. The beauty of using this tool is that it automatically regenerate the docs whenever the source code is updated. It also allows the users to try it out right from the same page by making requests to the endpoints.

In OpenCatapult API, the Swagger can be accessed from the root URL. However, it is only active in the Development environment because it only makes sense for development purpose.

If you use one of the build scripts to run the API component, it will run in the Development environment by default. But if you don’t use the build script, you might want to set the environment variable first:

$env:ASPNETCORE_ENVIRONMENT=Development

Accessing the API root URL in the Development environment will take you to a beautiful Swagger UI. You can see the list of all API endpoints, along with the payloads schema and samples.

You can also try each of the endpoints right from the page. Please be aware of the “lock” icon though because it means the endpoint requires authorization. You need to retrieve an authentication token first by making a request to the /Token endpoint along with the user’s email and password.

Take note of the token value from the response body because it will be used to authorize your requests to other endpoints.

Click on the Authorize button on top of the page, and enter bearer [token] as the value.

Swagger%20UI(5)

When authorized, you can try to execute any secure endpoints now.

1 Like