Api Documentation Generator

Name: Api Documentation Generator
Author: aiskillstore

aiskillstore/marketplace

2 installs
404 repo stars
Updated August 5, 2026
aiskillstore/marketplace

api-documentation-generator is a Claude Code skill that generates OpenAPI/Swagger documentation from a codebase's API route files.

About

api-documentation-generator scans a codebase for API route definitions and produces an OpenAPI 3.0 (Swagger) specification from them. It recognizes Express, FastAPI, Flask, NestJS and Rails route patterns, extracts methods, paths, parameters and responses, and writes an openapi.yaml. A developer uses it to create or update API docs without hand-writing the spec.

Generates OpenAPI 3.0 (Swagger) specs from existing API route files
Detects Express, FastAPI, Flask, NestJS and Rails route patterns
Ships a base openapi-3.0.yaml template plus framework examples

Api Documentation Generator by the numbers

2 all-time installs (skills.sh)
Ranked #1,294 of 1,879 Documentation skills by installs in the Skillselion catalog
Data as of Aug 5, 2026 (Skillselion catalog sync)

At a glance

api-documentation-generator capabilities & compatibility

Capabilities: api documentation · openapi generation · route discovery
Use cases: documentation · api development

From the docs

What api-documentation-generator says it does

This skill automatically generates OpenAPI 3.0 (Swagger) documentation from API route files in your codebase.

SKILL.md

Generates OpenAPI/Swagger documentation from API route files. Use when working with REST APIs, Express routes, FastAPI endpoints, or when user requests API documentation.

SKILL.md

npx skills add https://github.com/aiskillstore/marketplace --skill api-documentation-generator

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/aiskillstore/marketplace/api-documentation-generator.svg)](https://skillselion.com/skills/aiskillstore/marketplace/api-documentation-generator)

Installs	2
repo stars	★ 404
Last updated	August 5, 2026
Repository	aiskillstore/marketplace ↗

What it does

Generate or update OpenAPI/Swagger documentation from existing REST API route files across common web frameworks.

Who is it for?

Turning existing Express, FastAPI, Flask, NestJS or Rails routes into an OpenAPI 3.0 spec.

Skip if: Designing an API from scratch or generating client SDKs.

When should I use this skill?

A developer asks to generate or update API documentation for a REST API.

What you get

An OpenAPI 3.0 specification file that mirrors the codebase's real endpoints.

OpenAPI 3.0 specification file
endpoint-to-path mappings grouped by tags

By the numbers

5-step generation workflow
supports 5 web frameworks (Express, FastAPI, Flask, NestJS, Rails)

Files

SKILL.mdMarkdownGitHub ↗

API Documentation Generator

This skill automatically generates OpenAPI 3.0 (Swagger) documentation from API route files in your codebase.

When to Use This Skill

User asks to generate API documentation
Working with REST API endpoints
Need to create or update OpenAPI/Swagger specs
Setting up API documentation for Express, FastAPI, Flask, NestJS, or similar frameworks

Instructions

1. Discover API Routes

Search the codebase for API route definitions:

Express/Node.js: Look for app.get(), app.post(), router.get(), etc.
FastAPI/Python: Look for @app.get(), @router.post(), decorators
Flask: Look for @app.route() decorators
NestJS: Look for @Get(), @Post(), @Controller() decorators
Rails: Look for routes in config/routes.rb

Use Glob to find route files (e.g., **/*routes*.{js,ts,py}, **/controllers/**/*.{js,ts})

2. Analyze Route Patterns

For each discovered route, extract:

HTTP Method: GET, POST, PUT, PATCH, DELETE
Path: The endpoint URL (e.g., /api/users/:id)
Parameters: Path params, query params, request body
Response: Expected response structure
Authentication: Whether auth is required
Description: Comments or docstrings near the route

3. Generate OpenAPI Specification

Create or update an OpenAPI 3.0 specification file (typically openapi.yaml or swagger.json):

Start with the template from templates/openapi-3.0.yaml
Map each route to an OpenAPI path object
Define request/response schemas using JSON Schema
Include parameter definitions (path, query, body)
Add authentication schemes if detected (Bearer, API Key, OAuth2)
Group endpoints by tags (e.g., "Users", "Products", "Auth")

4. Validate Completeness

Check that the generated documentation includes:

All discovered endpoints
Accurate HTTP methods and paths
Request/response examples where possible
Error responses (400, 401, 404, 500, etc.)
Security requirements

5. Output Location

Save as openapi.yaml in the project root, or
Place in docs/ or api/ directory if those exist
Ask user for preferred location if unclear

Framework-Specific Notes

Express/Node.js

Check for route middleware that might affect auth/validation
Look for request validators (Joi, express-validator, etc.)
Extract JSDoc comments for endpoint descriptions

FastAPI

FastAPI auto-generates OpenAPI docs, but this skill can enhance them
Extract Pydantic models for request/response schemas
Check for response_model and status_code parameters

NestJS

Look for DTOs (Data Transfer Objects) for schemas
Check for Swagger decorators (@ApiOperation, @ApiResponse)
Extract metadata from controller and method decorators

Best Practices

1. Use existing schemas: If the codebase has TypeScript interfaces, Pydantic models, or similar, use them for accurate schemas 2. Include examples: Add request/response examples from tests if available 3. Group logically: Organize endpoints by resource or feature area using tags 4. Version appropriately: Use the API version from the codebase (e.g., "1.0.0") 5. Add descriptions: Use code comments/docstrings for endpoint descriptions

Supporting Files

templates/openapi-3.0.yaml: Base OpenAPI template
examples.md: Framework-specific examples

API Documentation Generator Examples

Express.js Example

Input Route Code

// routes/users.js
const express = require('express');
const router = express.Router();

/**
 * Get user by ID
 * @route GET /api/users/:id
 * @param {string} id - User ID
 * @returns {User} 200 - User object
 * @returns {Error} 404 - User not found
 */
router.get('/:id', async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) {
    return res.status(404).json({ error: 'User not found' });
  }
  res.json(user);
});

/**
 * Create new user
 * @route POST /api/users
 * @param {CreateUserDTO} request.body - User data
 * @returns {User} 201 - Created user
 */
router.post('/', async (req, res) => {
  const user = await User.create(req.body);
  res.status(201).json(user);
});

module.exports = router;

Generated OpenAPI

paths:
  /api/users/{id}:
    get:
      summary: Get user by ID
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          description: User ID
          schema:
            type: string
      responses:
        '200':
          description: User object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/users:
    post:
      summary: Create new user
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserDTO'
      responses:
        '201':
          description: Created user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

FastAPI Example

Input Route Code

from fastapi import APIRouter, HTTPException, Depends
from pydantic import BaseModel

router = APIRouter(prefix="/api/users", tags=["Users"])

class UserResponse(BaseModel):
    id: str
    email: str
    name: str

class CreateUserRequest(BaseModel):
    email: str
    name: str
    password: str

@router.get("/{user_id}", response_model=UserResponse)
async def get_user(user_id: str):
    """
    Get user by ID

    Returns user details if found, otherwise 404
    """
    user = await User.find_by_id(user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user

@router.post("/", response_model=UserResponse, status_code=201)
async def create_user(data: CreateUserRequest):
    """Create a new user account"""
    user = await User.create(**data.dict())
    return user

Generated OpenAPI

FastAPI auto-generates OpenAPI, but this skill can enhance it with:

Additional examples from tests
More detailed descriptions
Security scheme configurations
Server configurations

NestJS Example

Input Controller Code

import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';

@ApiTags('users')
@Controller('api/users')
export class UsersController {

  @Get(':id')
  @ApiOperation({ summary: 'Get user by ID' })
  @ApiResponse({ status: 200, description: 'User found', type: UserDto })
  @ApiResponse({ status: 404, description: 'User not found' })
  async getUser(@Param('id') id: string): Promise<UserDto> {
    return this.usersService.findOne(id);
  }

  @Post()
  @ApiOperation({ summary: 'Create new user' })
  @ApiResponse({ status: 201, description: 'User created', type: UserDto })
  async createUser(@Body() createUserDto: CreateUserDto): Promise<UserDto> {
    return this.usersService.create(createUserDto);
  }
}

Generated OpenAPI

NestJS with Swagger decorators already provides good documentation. This skill:

Ensures consistency across all controllers
Adds missing error responses
Extracts DTOs for complete schemas
Validates documentation completeness

Flask Example

Input Route Code

from flask import Flask, request, jsonify
from flask_restful import Resource, Api

app = Flask(__name__)
api = Api(app)

class UserResource(Resource):
    """User management endpoints"""

    def get(self, user_id):
        """
        Get user by ID
        ---
        parameters:
          - name: user_id
            in: path
            type: string
            required: true
        responses:
          200:
            description: User details
          404:
            description: User not found
        """
        user = User.query.get(user_id)
        if not user:
            return {'error': 'User not found'}, 404
        return user.to_dict()

    def post(self):
        """
        Create new user
        ---
        parameters:
          - name: body
            in: body
            schema:
              type: object
              properties:
                email:
                  type: string
                name:
                  type: string
        responses:
          201:
            description: User created
        """
        data = request.get_json()
        user = User(**data)
        db.session.add(user)
        db.session.commit()
        return user.to_dict(), 201

api.add_resource(UserResource, '/api/users/<user_id>', '/api/users')

Rails Example

Input Routes

# config/routes.rb
Rails.application.routes.draw do
  namespace :api do
    namespace :v1 do
      resources :users, only: [:index, :show, :create, :update, :destroy]
      post 'auth/login', to: 'authentication#login'
    end
  end
end

# app/controllers/api/v1/users_controller.rb
module Api
  module V1
    class UsersController < ApplicationController
      # GET /api/v1/users
      def index
        @users = User.all
        render json: @users
      end

      # GET /api/v1/users/:id
      def show
        @user = User.find(params[:id])
        render json: @user
      rescue ActiveRecord::RecordNotFound
        render json: { error: 'User not found' }, status: :not_found
      end

      # POST /api/v1/users
      def create
        @user = User.new(user_params)
        if @user.save
          render json: @user, status: :created
        else
          render json: { errors: @user.errors }, status: :unprocessable_entity
        end
      end
    end
  end
end

Generated OpenAPI

paths:
  /api/v1/users:
    get:
      summary: List all users
      tags:
        - Users
      responses:
        '200':
          description: Array of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

    post:
      summary: Create new user
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
        '422':
          description: Validation errors

  /api/v1/users/{id}:
    get:
      summary: Get user by ID
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User details
        '404':
          description: User not found

{
  "schema_version": "2.0",
  "meta": {
    "generated_at": "2026-01-16T23:24:43.605Z",
    "slug": "crazydubya-api-documentation-generator",
    "source_url": "https://github.com/CrazyDubya/claude-skills/tree/main/api-documentation-generator",
    "source_ref": "main",
    "model": "claude",
    "analysis_version": "3.0.0",
    "source_type": "community",
    "content_hash": "0d8b57c76756c5cb7e7a6a1b33ee204d2639241261a3b3c719ee5f45e1504578",
    "tree_hash": "294d4b4601fdaa7870ea3f46879d9566c9968b7b5f3ce4a46a8369034da27088"
  },
  "skill": {
    "name": "api-documentation-generator",
    "description": "Generates OpenAPI/Swagger documentation from API route files. Use when working with REST APIs, Express routes, FastAPI endpoints, or when user requests API documentation.",
    "summary": "Generates OpenAPI/Swagger documentation from API route files. Use when working with REST APIs, Expre...",
    "icon": "📚",
    "version": "1.0.0",
    "author": "CrazyDubya",
    "license": "MIT",
    "category": "documentation",
    "tags": [
      "api",
      "openapi",
      "swagger",
      "documentation",
      "rest"
    ],
    "supported_tools": [
      "claude",
      "codex",
      "claude-code"
    ],
    "risk_factors": [
      "external_commands",
      "network"
    ]
  },
  "security_audit": {
    "risk_level": "safe",
    "is_blocked": false,
    "safe_to_publish": true,
    "summary": "This is a prompt-based documentation skill with no executable code. It provides instructions for generating OpenAPI documentation and includes template files and examples. All static findings are false positives triggered by documentation patterns (HTTP method names, API endpoint syntax, and security concept references). No network access, no file system manipulation beyond normal AI operations, and no data collection.",
    "risk_factor_evidence": [
      {
        "factor": "external_commands",
        "evidence": [
          {
            "file": "examples.md",
            "line_start": 6,
            "line_end": 38
          },
          {
            "file": "examples.md",
            "line_start": 38,
            "line_end": 41
          },
          {
            "file": "examples.md",
            "line_start": 41,
            "line_end": 87
          },
          {
            "file": "examples.md",
            "line_start": 87,
            "line_end": 92
          },
          {
            "file": "examples.md",
            "line_start": 92,
            "line_end": 125
          },
          {
            "file": "examples.md",
            "line_start": 125,
            "line_end": 137
          },
          {
            "file": "examples.md",
            "line_start": 137,
            "line_end": 160
          },
          {
            "file": "examples.md",
            "line_start": 160,
            "line_end": 172
          },
          {
            "file": "examples.md",
            "line_start": 172,
            "line_end": 227
          },
          {
            "file": "examples.md",
            "line_start": 227,
            "line_end": 232
          },
          {
            "file": "examples.md",
            "line_start": 232,
            "line_end": 273
          },
          {
            "file": "examples.md",
            "line_start": 273,
            "line_end": 276
          },
          {
            "file": "examples.md",
            "line_start": 276,
            "line_end": 325
          },
          {
            "file": "SKILL.md",
            "line_start": 24,
            "line_end": 24
          },
          {
            "file": "SKILL.md",
            "line_start": 24,
            "line_end": 24
          },
          {
            "file": "SKILL.md",
            "line_start": 24,
            "line_end": 24
          },
          {
            "file": "SKILL.md",
            "line_start": 25,
            "line_end": 25
          },
          {
            "file": "SKILL.md",
            "line_start": 25,
            "line_end": 25
          },
          {
            "file": "SKILL.md",
            "line_start": 26,
            "line_end": 26
          },
          {
            "file": "SKILL.md",
            "line_start": 27,
            "line_end": 27
          },
          {
            "file": "SKILL.md",
            "line_start": 27,
            "line_end": 27
          },
          {
            "file": "SKILL.md",
            "line_start": 27,
            "line_end": 27
          },
          {
            "file": "SKILL.md",
            "line_start": 28,
            "line_end": 28
          },
          {
            "file": "SKILL.md",
            "line_start": 30,
            "line_end": 30
          },
          {
            "file": "SKILL.md",
            "line_start": 30,
            "line_end": 30
          },
          {
            "file": "SKILL.md",
            "line_start": 37,
            "line_end": 37
          },
          {
            "file": "SKILL.md",
            "line_start": 45,
            "line_end": 45
          },
          {
            "file": "SKILL.md",
            "line_start": 45,
            "line_end": 45
          },
          {
            "file": "SKILL.md",
            "line_start": 47,
            "line_end": 47
          },
          {
            "file": "SKILL.md",
            "line_start": 66,
            "line_end": 66
          },
          {
            "file": "SKILL.md",
            "line_start": 67,
            "line_end": 67
          },
          {
            "file": "SKILL.md",
            "line_start": 67,
            "line_end": 67
          },
          {
            "file": "SKILL.md",
            "line_start": 80,
            "line_end": 80
          },
          {
            "file": "SKILL.md",
            "line_start": 80,
            "line_end": 80
          },
          {
            "file": "SKILL.md",
            "line_start": 84,
            "line_end": 84
          },
          {
            "file": "SKILL.md",
            "line_start": 84,
            "line_end": 84
          },
          {
            "file": "SKILL.md",
            "line_start": 97,
            "line_end": 97
          },
          {
            "file": "SKILL.md",
            "line_start": 98,
            "line_end": 98
          }
        ]
      },
      {
        "factor": "network",
        "evidence": [
          {
            "file": "skill-report.json",
            "line_start": 6,
            "line_end": 6
          },
          {
            "file": "templates/openapi-3.0.yaml",
            "line_start": 11,
            "line_end": 11
          },
          {
            "file": "templates/openapi-3.0.yaml",
            "line_start": 14,
            "line_end": 14
          },
          {
            "file": "templates/openapi-3.0.yaml",
            "line_start": 16,
            "line_end": 16
          }
        ]
      }
    ],
    "critical_findings": [],
    "high_findings": [],
    "medium_findings": [],
    "low_findings": [],
    "dangerous_patterns": [],
    "files_scanned": 4,
    "total_lines": 737,
    "audit_model": "claude",
    "audited_at": "2026-01-16T23:24:43.605Z"
  },
  "content": {
    "user_title": "Generate OpenAPI documentation from API routes",
    "value_statement": "Creating API documentation manually takes hours of work. This skill automatically analyzes Express, FastAPI, NestJS, Flask, and Rails route files to generate complete OpenAPI 3.0 specifications with schemas, parameters, and responses.",
    "seo_keywords": [
      "API documentation generator",
      "OpenAPI 3.0",
      "Swagger documentation",
      "Claude Code skill",
      "REST API docs",
      "Express API docs",
      "FastAPI documentation",
      "NestJS Swagger",
      "API spec generator"
    ],
    "actual_capabilities": [
      "Discovers API routes across Express, FastAPI, NestJS, Flask, and Rails codebases",
      "Extracts HTTP methods, paths, parameters, and response structures from route files",
      "Generates OpenAPI 3.0 YAML specifications with proper schema definitions",
      "Creates request and response schemas using JSON Schema standards",
      "Groups endpoints by resource using tags for organized documentation",
      "Adds security scheme configurations for Bearer, API Key, and OAuth2 authentication"
    ],
    "limitations": [
      "Cannot execute code to discover dynamic routes at runtime",
      "Requires source code access to route files for analysis",
      "Does not validate generated documentation against running APIs",
      "Cannot infer complex request body structures without explicit type definitions"
    ],
    "use_cases": [
      {
        "target_user": "Backend developers",
        "title": "Document REST APIs",
        "description": "Automatically generate OpenAPI specs from Express, FastAPI, or NestJS route definitions for API consumers."
      },
      {
        "target_user": "Tech writers",
        "title": "Create API reference docs",
        "description": "Transform codebase route files into Swagger UI-ready documentation without manual specification writing."
      },
      {
        "target_user": "DevOps engineers",
        "title": "Generate API contracts",
        "description": "Create standardized OpenAPI specifications for API gateway configurations and integration testing."
      }
    ],
    "prompt_templates": [
      {
        "title": "Basic API docs",
        "scenario": "Generate documentation for an Express API",
        "prompt": "Use the API Documentation Generator skill to analyze my Express routes and generate an openapi.yaml file in the project root."
      },
      {
        "title": "FastAPI enhancement",
        "scenario": "Enhance existing FastAPI OpenAPI docs",
        "prompt": "Use the API Documentation Generator skill to read my FastAPI endpoints and enhance the auto-generated OpenAPI docs with additional examples and detailed error responses."
      },
      {
        "title": "Multi-framework",
        "scenario": "Document mixed codebase",
        "prompt": "Use the API Documentation Generator to find all API routes in my codebase, including Express routes in the backend folder and Flask APIs in the api directory, then generate a unified OpenAPI specification."
      },
      {
        "title": "Complete spec",
        "scenario": "Generate full documentation with security",
        "prompt": "Generate comprehensive OpenAPI 3.0 documentation for my REST API. Include all discovered endpoints, request/response schemas, authentication requirements, and group them by Users, Products, and Orders tags."
      }
    ],
    "output_examples": [
      {
        "input": "Generate OpenAPI documentation for my Express API routes",
        "output": [
          "Generated openapi.yaml with 12 endpoints across 3 tags",
          "Created schemas: User, CreateUserRequest, Product, Order",
          "Added authentication schemes: BearerAuth (JWT) and ApiKeyAuth",
          "Included error responses: 400, 401, 404, 500",
          "Saved to: /project/openapi.yaml"
        ]
      },
      {
        "input": "Create API docs for my FastAPI backend",
        "output": [
          "Analyzed 8 endpoints in routes/users.py and routes/products.py",
          "Extracted Pydantic models for UserResponse, ProductCreate",
          "Generated OpenAPI 3.0 spec with pagination parameters",
          "Added 401 and 422 error response definitions"
        ]
      }
    ],
    "best_practices": [
      "Run the skill after adding new endpoints to keep documentation current",
      "Review generated schemas against actual API behavior before publishing",
      "Add JSDoc comments or docstrings to routes for richer endpoint descriptions"
    ],
    "anti_patterns": [
      "Using generated docs without verifying response accuracy",
      "Skipping security scheme configuration for authenticated endpoints",
      "Generating documentation without access to route source files"
    ],
    "faq": [
      {
        "question": "Which frameworks does this skill support?",
        "answer": "Express, FastAPI, NestJS, Flask, and Ruby on Rails. It analyzes route decorators and definitions to extract endpoint information."
      },
      {
        "question": "What is the maximum number of endpoints it can document?",
        "answer": "There is no hard limit. The skill processes endpoints in batches and generates specifications for all discovered routes."
      },
      {
        "question": "Can it integrate with existing OpenAPI files?",
        "answer": "Yes. The skill can read existing specifications and add or update endpoints without overwriting custom configurations."
      },
      {
        "question": "Does this skill send my code to external services?",
        "answer": "No. All analysis happens locally within the AI context. The generated OpenAPI file is saved directly to your project."
      },
      {
        "question": "Why is my generated documentation missing some endpoints?",
        "answer": "Ensure route files are accessible and use standard framework patterns. Non-standard routing or dynamically generated routes may not be detected."
      },
      {
        "question": "How does this compare to framework auto-docs?",
        "answer": "FastAPI and NestJS auto-generate docs, but this skill enhances them with examples, error details, and cross-framework consistency for multi-language projects."
      }
    ]
  },
  "file_structure": [
    {
      "name": "templates",
      "type": "dir",
      "path": "templates",
      "children": [
        {
          "name": "openapi-3.0.yaml",
          "type": "file",
          "path": "templates/openapi-3.0.yaml",
          "lines": 119
        }
      ]
    },
    {
      "name": "examples.md",
      "type": "file",
      "path": "examples.md",
      "lines": 326
    },
    {
      "name": "SKILL.md",
      "type": "file",
      "path": "SKILL.md",
      "lines": 99
    }
  ]
}

openapi: 3.0.3
info:
  title: API Documentation
  description: Auto-generated API documentation
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:3000
    description: Development server
  - url: https://api.example.com
    description: Production server

tags:
  - name: Authentication
    description: User authentication and authorization
  - name: Users
    description: User management operations
  - name: Resources
    description: Resource CRUD operations

paths:
  /api/example:
    get:
      summary: Example endpoint
      description: This is an example endpoint description
      tags:
        - Resources
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  page:
                    type: integer
                  total:
                    type: integer
              example:
                data: []
                page: 1
                total: 0
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
      required:
        - error

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT authentication token
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication

security:
  - BearerAuth: []