Skip to content

Swagger/OpenAPI Documentation

Last Updated: 2025-11-24

Ocmonica's REST API is documented using OpenAPI (Swagger) 3.0 specification, providing interactive API exploration and testing capabilities.

Overview

The Swagger documentation is automatically generated from Go code annotations in the REST handlers. It provides:

  • ✅ Interactive API Explorer - Test endpoints directly from the browser
  • ✅ Complete API Reference - All REST endpoints documented with examples
  • ✅ Request/Response Schemas - Full type definitions and validation rules
  • ✅ Authentication Support - Built-in JWT and API Key authentication
  • ✅ Try It Out - Execute real API calls with authentication

Accessing Swagger UI

When the server is running, access Swagger UI at:

Local Development: 

http://localhost:8080/swagger/index.html

Production: 

https://your-domain.com/swagger/index.html

Alternative Formats

The OpenAPI specification is available in multiple formats:

  • Interactive UI: http://localhost:8080/swagger/index.html
  • JSON Spec: http://localhost:8080/swagger/doc.json
  • YAML Spec: View docs/swagger/swagger.yaml in this repository

Using Swagger UI

1. Authenticate

Most endpoints require authentication. To use protected endpoints:

  1. Click the Authorize button (lock icon) in the top right
  2. Enter your JWT token in the format: Bearer <your_access_token>
  3. Or enter your API key in the X-API-Key field
  4. Click Authorize

Getting a Token: 

# Login via REST API
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

# Copy the access_token from the response
# Use it in Swagger UI: Bearer eyJhbGciOiJSUzI1NiIs...

2. Explore Endpoints

  • Browse endpoints by category (tags): Files, Directories, Auth, Organizations, etc.
  • Click any endpoint to expand details
  • View request parameters, request body schema, and response examples

3. Try It Out

  1. Click the Try it out button on any endpoint
  2. Fill in required parameters
  3. Click Execute
  4. View the response, including status code, headers, and body

API Categories

The Swagger documentation organizes endpoints into the following categories:

Category Description Endpoints
Authentication User registration, login, token management /auth/*
Files File upload, download, metadata management /files/*
Directories Directory operations and navigation /directories/*
Search File and directory search /search
Organizations Multi-tenant organization management /organizations/*
Roles RBAC role management /roles/*
Users User management /users/*
Groups Group management /groups/*
API Keys API key generation and management /api-keys/*
Watched Folders Filesystem monitoring configuration /watched-folders/*
Health Health checks and system status /health

OpenAPI Specification Files

The Swagger documentation is available in multiple formats in the docs/swagger/ directory:

swagger.json

OpenAPI 3.0 specification in JSON format. Ideal for: - API client generation - CI/CD validation - Third-party tools integration

Size: ~200KB

swagger.yaml

OpenAPI 3.0 specification in YAML format. Ideal for: - Human-readable format - Version control diffs - Manual editing (though we generate from code)

Size: ~96KB

docs.go

Go source code with embedded Swagger documentation. Used by: - swaggo/echo-swagger middleware - Serving Swagger UI at runtime

DO NOT EDIT THIS FILE - It's auto-generated from handler annotations.

Automatic Regeneration

Swagger documentation is automatically regenerated when REST handler files change.

Pre-commit Hook

The lefthook.yml configuration includes a swagger-gen hook that:

  1. Watches: internal/api/rest/handlers/*.go
  2. Runs: swag init -g cmd/server/main.go -o docs/swagger --parseDependency --parseInternal
  3. Output: Regenerates all files in docs/swagger/

Manual regeneration: 

task swagger:gen
# Or: swag init -g cmd/server/main.go -o docs/swagger --parseDependency --parseInternal

Requirements

The swag CLI tool must be installed: 

go install github.com/swaggo/swag/cmd/swag@latest

If not installed, the pre-commit hook will skip regeneration with a warning.

Adding New Endpoints

When adding new REST endpoints, annotate them with Swagger comments:

Example: 

// Upload godoc
//
// @Summary Upload a file
// @Description Upload a new file to the system
// @Tags files
// @Accept multipart/form-data
// @Produce json
// @Param file formData file true "File to upload"
// @Param directory_id formData string false "Parent directory ID"
// @Success 201 {object} models.File "File uploaded successfully"
// @Failure 400 {object} map[string]string "Invalid request"
// @Failure 401 {object} map[string]string "Unauthorized"
// @Security BearerAuth
// @Router /files [post]
func (h *FileHandler) Upload(c echo.Context) error {
    // Implementation...
}

After adding annotations: 1. Run task swagger:gen to regenerate documentation 2. Refresh Swagger UI to see the new endpoint 3. Commit the generated files in docs/swagger/

For detailed annotation patterns, see the Swagger comments in the handler files at internal/api/rest/handlers/.

Security Definitions

Swagger UI supports two authentication methods:

Bearer Authentication (JWT)

securityDefinitions:
  BearerAuth:
    type: apiKey
    in: header
    name: Authorization
    description: Type "Bearer" followed by a space and JWT token.

Usage: Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

API Key Authentication

securityDefinitions:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key
    description: API key for authentication

Usage: X-API-Key: your-api-key-here

Common Use Cases

Testing Authenticated Endpoints

  1. Login via /auth/login endpoint in Swagger UI
  2. Copy the access_token from the response
  3. Click Authorize and paste the token with "Bearer " prefix
  4. All subsequent requests will include authentication

Downloading Files

  1. Use /files/{id}/download endpoint
  2. Click Try it out
  3. Enter the file ID
  4. Click Execute
  5. Click the Download file link in the response

Uploading Files

  1. Use /files POST endpoint
  2. Click Try it out
  3. Click Choose File to select a file from your computer
  4. Optionally enter a directory_id
  5. Click Execute
  6. View the uploaded file metadata in the response

Limitations

Not Available in Swagger

The following are NOT documented in Swagger (use gRPC API documentation instead):

  • Server streaming - Search streaming endpoints
  • Bidirectional streaming - Real-time file sync
  • Binary file transfers - Efficient large file uploads (use REST multipart instead)

For these features, see: - gRPC API Documentation - gRPC OpenAPI Documentation

Swagger UI Limitations

  • Cannot test file downloads directly (use curl or frontend)
  • Multipart file uploads require manual file selection
  • Large file transfers may timeout in browser

Troubleshooting

Swagger UI Not Loading

Problem: 404 error when accessing /swagger/index.html

Solution: 1. Ensure server is running: task dev 2. Verify Swagger files exist: ls docs/swagger/ 3. Regenerate if missing: task swagger:gen

Endpoints Not Appearing

Problem: New endpoints don't show up in Swagger UI

Solution: 1. Check handler has @Router annotation 2. Regenerate documentation: task swagger:gen 3. Restart the server 4. Hard refresh browser (Cmd+Shift+R / Ctrl+Shift+R)

Authentication Failing

Problem: Getting 401 errors despite entering token

Solution: 1. Ensure token is prefixed with "Bearer " (with space) 2. Verify token hasn't expired (15min lifetime) 3. Use refresh token to get a new access token 4. Check token was copied correctly (no extra characters)

swag Command Not Found

Problem: Pre-commit hook shows "swag not installed"

Solution: 

go install github.com/swaggo/swag/cmd/swag@latest

See Also

External Resources