Endpoints and Swagger
Swagger is an open-source framework used to design, document, and test RESTful APIs. It provides an interactive Swagger UI that allows developers to explore API endpoints, send test requests, and view responses without using external tools like Postman.
Swagger follows the OpenAPI Specification (OAS), which standardizes API documentation. This makes it easier to share and understand API structures across teams.
In our backend, we use Swagger to automatically generate up-to-date, interactive API documentation based on our Go code. This helps both backend and frontend teams understand available endpoints, verify responses, and debug faster during development. Swagger also supports testing endpoints in real time and plays a key role in onboarding new developers.
For more details, visit: https://github.com/swaggo/swag
In our system, Swagger is integrated using the Swaggo tool, which parses specially formatted comments in our Go code to generate an OpenAPI definition.
The Swagger UI is accessible at: https:///api/v1/swagger
Example: https://app.dev.green-ecolution.de/api/v1/swagger
All configuration is automatically generated during build time, so the documentation always reflects the current state of the code.
We use Swaggo annotations directly in our Go code to define API routes, request/response types, and metadata.
To keep this documentation focused, we won’t go into detail here. For a complete guide on writing Swagger annotations, please refer to the official Swaggo documentation:
Swaggo: Declarative Comments Format
If needed, examples of annotation usage can be found in the codebase (e.g., GetAppInfo() route).
Our system secures API access using Keycloak, an identity and access management solution. When accessing protected API endpoints in Swagger, users must first authenticate via OAuth2 (accessCode flow).
- Click the "Authorize" button in the Swagger UI.
- Enter the required client_id and client_secret.
- Swagger will request an access token from Keycloak.
- The token is included in subsequent API requests for authentication.
Here’s an example of the Keycloak authentication popup in Swagger:
