Документация API (Swagger)
Relevant source files
The following files were used as context for generating this wiki page:
The API documentation for the Music Subscription Service is implemented using the Swagger (OpenAPI 2.0) standard via the swaggo library. It provides a web-based interface for developers to explore, test, and integrate with the backend services. The documentation covers all available endpoints, including authentication, track management, playlists, and administrative functions.
The Swagger UI is an essential part of the development workflow, allowing for real-time interaction with the REST API. It serves as the primary technical reference for endpoint signatures, request/response models, and security requirements.
Sources: README.md:143-145, cmd/app/main.go:37-47
API Configuration and Access
The Swagger documentation is generated from annotations in the source code. The main entry point for the API metadata is located in the main.go file, which defines the global settings such as the title, version, and security definitions.
Accessing Swagger UI
When the application is running, the documentation is accessible at the following URL:
http://localhost:8080/swagger/index.html
Sources: README.md:20-22, README.md:149-151
Global Metadata
The following table summarizes the global API configuration:
| Field | Value | Description |
|---|---|---|
| Title | Music Subscription Service API | Official name of the service |
| Version | 1.0 | Current API version |
| Host | localhost:8080 | Default host for local development |
| BasePath | /api/v1 | Prefix for all API routes |
Sources: cmd/app/main.go:37-41
Implementation Architecture
The Swagger integration is built into the application startup sequence. It involves importing the generated docs and wrapping the Swagger handler within the Chi router.
Documentation Workflow
The following diagram illustrates how Swagger documentation is served by the application:
The diagram shows the transition from code-level annotations to the final UI served over HTTP.
Sources: cmd/app/main.go:20, cmd/app/main.go:121, README.md:104
Routing and Middleware
The Swagger route is registered as a public endpoint, meaning it does not require JWT authentication to view the UI itself, although individual API calls within the UI may require tokens.
// Swagger Route
r.Get("/swagger/*", httpSwagger.WrapHandler)
Sources: cmd/app/main.go:121
Security and Authorization
The API uses JWT (JSON Web Tokens) for securing protected routes. Swagger is configured to support BearerAuth, allowing users to provide their access tokens directly in the UI.
Security Definitions
The security scheme is defined in the header of main.go:
- Type: API Key
- Name: Authorization
- In: Header
- Format:
Bearer <token>
Sources: cmd/app/main.go:43-46
Authorization Flow
To test protected endpoints, users must first obtain a token via the /api/v1/auth/login endpoint and then use the Authorize button in Swagger UI.
The sequence diagram details the process of authenticating through the UI to access protected resources.
Sources: README.md:88-91, internal/core/middleware/middleware.go:119-125
Endpoint Documentation Examples
Each endpoint is documented using specific godoc comments above the handler functions. These comments define the summary, description, tags, parameters, and expected responses.
Track Creation (Admin)
The track creation endpoint is restricted to users with the ADMIN role. Its Swagger documentation specifies the requirement for BearerAuth and the specific structure of the CreateTrackRequest.
| Component | Detail |
|---|---|
| Summary | Create a new track |
| Tags | admin |
| Security | BearerAuth |
| Success Code | 201 (Created) |
| Failure Codes | 400, 401, 403, 500 |
Sources: internal/features/tracks/transport/http/create.go:11-25
Code Annotation Example
// @Summary Create a new track
// @Description Create a new music track (ADMIN only)
// @Tags admin
// @Accept json
// @Produce json
// @Param request body CreateTrackRequest true "Track configuration payload"
// @Success 201 {object} model.Track
// @Security BearerAuth
// @Router /admin/tracks [post]
Sources: internal/features/tracks/transport/http/create.go:11-25
Infrastructure and Tooling
The project provides automated ways to manage and update the Swagger documentation.
Automation with Makefile
The command make swag is used to trigger the swaggo CLI, which parses the source code and updates the files in the docs/ directory.
Sources: README.md:104
Docker Integration
A dedicated Swagger service is defined in docker-compose.yml to facilitate documentation generation within a containerized environment, ensuring consistent versions of the swag tool.
swagger:
build:
context: ${PROJECT_ROOT}
dockerfile_inline: |
FROM golang:alpine
RUN go install github.com/swaggo/swag/cmd/swag@v1.16.6
WORKDIR /code
ENTRYPOINT ["swag"]
Sources: docker-compose.yml:71-80
Conclusion
The Swagger API documentation provides a comprehensive, interactive roadmap for the Music Subscription Service. By integrating documentation directly into the development workflow via code annotations and automated build tools, the project ensures that the API reference remains accurate and synchronized with the actual implementation. This setup facilitates efficient collaboration between backend and frontend developers and simplifies the debugging of complex flows such as user authentication and track management.