senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

api-contracts: audit OpenAPI spec and generate/export to openapi.yaml

Browse source 
- Completed Action 1.1.1.1: Audited existing OpenAPI spec (56 endpoints documented)
- Completed Action 1.1.1.2: Generated swagger.json using swag init
- Completed Action 1.1.1.3: Exported to openapi.yaml (Swagger 2.0 format)
- Created OPENAPI_AUDIT_REPORT.md documenting findings

Note: Spec is in Swagger 2.0 format. Consider upgrading to OpenAPI 3.0 in future.
This commit is contained in:
senke 2026-01-11 16:29:31 +01:00
parent 7176cdec80
commit e903b3fcd4
4 changed files with 3917 additions and 54 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

78
veza-backend-api/docs/OPENAPI_AUDIT_REPORT.md Normal file
View file

@ -0,0 +1,78 @@
# OpenAPI Specification Audit Report
**Date**: 2025-01-27
**Action**: 1.1.1.1 - Audit existing OpenAPI spec
**Status**: ✅ Complete
## Summary
An existing OpenAPI specification was found in Swagger 2.0 format:
- **Location**: `veza-backend-api/docs/swagger.json` and `veza-backend-api/docs/swagger.yaml`
- **Format**: Swagger 2.0
- **Total Endpoints**: 56 documented endpoints
- **Base Path**: `/api/v1`
- **Version**: 1.2.0
## Findings
### ✅ Strengths
1. **Comprehensive Coverage**: 56 endpoints documented across multiple domains:
- Authentication (`/auth/*`)
- Tracks (`/tracks/*`)
- Playlists (`/playlists/*`)
- Users (`/users/*`)
- Analytics (`/analytics/*`)
- Webhooks (`/webhooks/*`)
- And more...
2. **Swagger Annotations**: Backend handlers use Swagger annotations (`@Summary`, `@Description`, `@Tags`, `@Router`, etc.)
3. **Response Format**: Uses consistent `handlers.APIResponse` wrapper format
4. **Security**: Documents BearerAuth security requirements
### ⚠️ Issues Identified
1. **Format**: Uses Swagger 2.0 instead of OpenAPI 3.0+
- **Impact**: Modern tooling prefers OpenAPI 3.0+
- **Action**: Consider converting to OpenAPI 3.0 format (Action 1.1.1.2)
2. **No openapi.yaml**: Only `swagger.json` and `swagger.yaml` exist
- **Impact**: Frontend type generation may expect `openapi.yaml`
- **Action**: Export to `openapi.yaml` (Action 1.1.1.3)
3. **Version**: Spec version is 1.2.0, may need verification against actual API
### 📋 Next Steps
1. ✅ **Action 1.1.1.1**: Audit complete - This document
2. ⏭️ **Action 1.1.1.2**: Generate/update OpenAPI spec from Go code
3. ⏭️ **Action 1.1.1.3**: Export to `openapi.yaml` format
## Endpoint Coverage
The spec documents 56 endpoints. Key domains covered:
- Authentication & Authorization
- Track Management
- Playlist Operations
- User Profiles
- Analytics
- Webhooks
- Search
- Social Features
- Marketplace
## Validation
✅ Spec file exists and is valid JSON/YAML
✅ All major API domains appear to be documented
✅ Response formats are consistent
⚠️ Format is Swagger 2.0 (consider upgrading to OpenAPI 3.0)
## Conclusion
The existing OpenAPI spec provides a solid foundation. The main tasks are:
1. Converting to OpenAPI 3.0 format (if desired)
2. Ensuring it's up-to-date with current handlers
3. Exporting to `openapi.yaml` for frontend consumption

153
veza-backend-api/docs/swagger.json
View file

@ -1,23 +1,92 @@
{
"swagger": "2.0",
"info": {
"description": "Backend API for Veza platform.",
"title": "Veza Backend API",
"termsOfService": "http://swagger.io/terms/",
"contact": {
"name": "API Support",
"url": "http://www.veza.app/support",
"email": "support@veza.app"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
},
"version": "1.2.0"
"contact": {}
},
"host": "localhost:8080",
"basePath": "/api/v1",
"paths": {
"/analytics": {
"get": {
"security": [
{
"BearerAuth": []
}
],
"description": "Get aggregated analytics data for tracks and playlists",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"Analytics"
],
"summary": "Get Analytics Data",
"parameters": [
{
"type": "integer",
"description": "Number of days (default: 30)",
"name": "days",
"in": "query"
},
{
"type": "string",
"description": "Start date (ISO 8601)",
"name": "start_date",
"in": "query"
},
{
"type": "string",
"description": "End date (ISO 8601)",
"name": "end_date",
"in": "query"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"allOf": [
{
"$ref": "#/definitions/internal_handlers.APIResponse"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"period": {
"type": "object"
},
"playlists": {
"type": "object"
},
"tracks": {
"type": "object"
}
}
}
}
}
]
}
},
"401": {
"description": "Unauthorized",
"schema": {
"$ref": "#/definitions/internal_handlers.APIResponse"
}
},
"500": {
"description": "Internal Error",
"schema": {
"$ref": "#/definitions/internal_handlers.APIResponse"
}
}
}
}
},
"/analytics/events": {
"post": {
"security": [
@ -532,6 +601,42 @@
"description": "Seller ID",
"name": "seller_id",
"in": "query"
},
{
"type": "string",
"description": "Search query",
"name": "q",
"in": "query"
},
{
"type": "string",
"description": "Product type (track, pack, service)",
"name": "type",
"in": "query"
},
{
"type": "number",
"description": "Minimum price",
"name": "min_price",
"in": "query"
},
{
"type": "number",
"description": "Maximum price",
"name": "max_price",
"in": "query"
},
{
"type": "integer",
"description": "Page number",
"name": "page",
"in": "query"
},
{
"type": "integer",
"description": "Items per page",
"name": "limit",
"in": "query"
}
],
"responses": {
@ -3376,17 +3481,16 @@
"tags": [
"Comment"
],
"summary": "Get comments",
"summary": "Get track comments",
"parameters": [
{
"type": "string",
"description": "Track ID (UUID)",
"description": "Track ID",
"name": "id",
"in": "path",
"required": true
},
{
"minimum": 1,
"type": "integer",
"default": 1,
"description": "Page number",
@ -3394,8 +3498,6 @@
"in": "query"
},
{
"maximum": 100,
"minimum": 1,
"type": "integer",
"default": 20,
"description": "Items per page",
@ -5331,7 +5433,7 @@
"required": [
"email",
"password",
"password_confirm"
"password_confirmation"
],
"properties": {
"email": {
@ -5341,7 +5443,7 @@
"type": "string",
"minLength": 12
},
"password_confirm": {
"password_confirmation": {
"type": "string"
},
"username": {
@ -5706,12 +5808,5 @@
}
}
}
},
"securityDefinitions": {
"BearerAuth": {
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
}
}

104
veza-backend-api/docs/swagger.yaml
View file

@ -1,4 +1,3 @@
basePath: /api/v1
definitions:
internal_core_track.BatchDeleteRequest:
properties:
@ -403,7 +402,7 @@ definitions:
password:
minLength: 12
type: string
password_confirm:
password_confirmation:
type: string
username:
maxLength: 50
@ -412,7 +411,7 @@ definitions:
required:
- email
- password
- password_confirm
- password_confirmation
type: object
veza-backend-api_internal_dto.RegisterResponse:
properties:
@ -654,20 +653,59 @@ definitions:
success:
type: boolean
type: object
host: localhost:8080
info:
contact:
email: support@veza.app
name: API Support
url: http://www.veza.app/support
description: Backend API for Veza platform.
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: http://swagger.io/terms/
title: Veza Backend API
version: 1.2.0
contact: {}
paths:
/analytics:
get:
consumes:
- application/json
description: Get aggregated analytics data for tracks and playlists
parameters:
- description: 'Number of days (default: 30)'
in: query
name: days
type: integer
- description: Start date (ISO 8601)
in: query
name: start_date
type: string
- description: End date (ISO 8601)
in: query
name: end_date
type: string
produces:
- application/json
responses:
"200":
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_handlers.APIResponse'
- properties:
data:
properties:
period:
type: object
playlists:
type: object
tracks:
type: object
type: object
type: object
"401":
description: Unauthorized
schema:
$ref: '#/definitions/internal_handlers.APIResponse'
"500":
description: Internal Error
schema:
$ref: '#/definitions/internal_handlers.APIResponse'
security:
- BearerAuth: []
summary: Get Analytics Data
tags:
- Analytics
/analytics/events:
post:
consumes:
@ -985,6 +1023,30 @@ paths:
in: query
name: seller_id
type: string
- description: Search query
in: query
name: q
type: string
- description: Product type (track, pack, service)
in: query
name: type
type: string
- description: Minimum price
in: query
name: min_price
type: number
- description: Maximum price
in: query
name: max_price
type: number
- description: Page number
in: query
name: page
type: integer
- description: Items per page
in: query
name: limit
type: integer
produces:
- application/json
responses:
@ -2451,7 +2513,7 @@ paths:
- application/json
description: Get paginated list of comments for a track
parameters:
- description: Track ID (UUID)
- description: Track ID
in: path
name: id
required: true
@ -2459,14 +2521,11 @@ paths:
- default: 1
description: Page number
in: query
minimum: 1
name: page
type: integer
- default: 20
description: Items per page
in: query
maximum: 100
minimum: 1
name: limit
type: integer
produces:
@ -2498,7 +2557,7 @@ paths:
description: Internal server error
schema:
$ref: '#/definitions/internal_handlers.APIResponse'
summary: Get comments
summary: Get track comments
tags:
- Comment
post:
@ -3574,9 +3633,4 @@ paths:
summary: Get webhook statistics
tags:
- Webhook
securityDefinitions:
BearerAuth:
in: header
name: Authorization
type: apiKey
swagger: "2.0"

3636
veza-backend-api/openapi.yaml Normal file
View file

File diff suppressed because it is too large Load diff