API dokumentácia

DEEPSEEK v3.2 PROMPT

23. API DOKUMENTÁCIA

Prompt: „Vygeneruj kompletnú API dokumentáciu pre funkciu [funkcia], vrátane parametrov, návratových hodnôt, chybových kódov a príkladov použitia."

---

ŠTRUKTÚRA API DOKUMENTÁCIE

ZÁKLADNÉ KOMPONENTY

• Endpoint: URL a HTTP metóda
• Description: Čo endpoint robí
• Parameters: Vstupné parametre
• Response: Štruktúra odpovede
• Error codes: Možné chyby
• Examples: Príklady použitia

ŠTANDARDY DOKUMENTÁCIE

• OpenAPI/Swagger: Štandard pre REST API
• Postman: API testing a dokumentácia
• Markdown: Jednoduchá textová dokumentácia
• JSDoc: JavaScript API dokumentácia

---

PRÍKLAD: USER MANAGEMENT API

ENDPOINT: CREATE USER

API DEFINITION

POST /api/v1/users
Content-Type: application/json
Authorization: Bearer <token>

DESCRIPTION

Vytvorí nového používateľa v systéme. Tento endpoint vyžaduje
autentifikáciu a validáciu vstupných dát. Vracia vytvoreného
používateľa s vygenerovaným ID a časom vytvorenia.

PARAMETERS

{
  "parameters": {
    "type": "object",
    "required": ["email", "password", "name"],
    "properties": {
      "email": {
        "type": "string",
        "format": "email",
        "description": "Emailová adresa používateľa. Musí byť unikátna.",
        "example": "john.doe@example.com",
        "minLength": 5,
        "maxLength": 255
      },
      "password": {
        "type": "string",
        "format": "password",
        "description": "Heslo používateľa. Minimálne 8 znakov, musí obsahovať veľké písmeno, malé písmeno a číslo.",
        "example": "SecurePass123!",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)[a-zA-Z\\d@$!%*?&]{8,}$"
      },
      "name": {
        "type": "string",
        "description": "Meno používateľa. Môže obsahovať medzery.",
        "example": "John Doe",
        "minLength": 1,
        "maxLength": 100
      },
      "role": {
        "type": "string",
        "enum": ["user", "admin", "moderator"],
        "description": "Rola používateľa. Predvolená hodnota je 'user'.",
        "default": "user",
        "example": "user"
      },
      "phone": {
        "type": "string",
        "description": "Telefónne číslo voliteľné. Formát: +421XXXXXXXXX.",
        "example": "+421900123456",
        "pattern": "^\\+[0-9]{10,15}$"
      },
      "avatar": {
        "type": "string",
        "format": "uri",
        "description": "URL adresa profilového obrázku. Voliteľné.",
        "example": "https://example.com/avatars/john.jpg"
      }
    }
  }
}

RESPONSES

{
  "responses": {
    "201": {
      "description": "Používateľ úspešne vytvorený",
      "content": {
        "type": "application/json",
        "schema": {
          "type": "object",
          "properties": {
            "success": {
              "type": "boolean",
              "example": true,
              "description": "Vždy true pri úspešnom vytvorení"
            },
            "data": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Unikátne ID používateľa",
                  "example": 12345
                },
                "email": {
                  "type": "string",
                  "format": "email",
                  "description": "Emailová adresa používateľa",
                  "example": "john.doe@example.com"
                },
                "name": {
                  "type": "string",
                  "description": "Meno používateľa",
                  "example": "John Doe"
                },
                "role": {
                  "type": "string",
                  "description": "Rola používateľa",
                  "example": "user"
                },
                "phone": {
                  "type": "string",
                  "description": "Telefónne číslo",
                  "example": "+421900123456"
                },
                "avatar": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL profilového obrázka",
                  "example": "https://example.com/avatars/john.jpg"
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Čas vytvorenia v ISO 8601 formáte",
                  "example": "2024-01-15T10:30:00Z"
                },
                "updated_at": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Čas poslednej úpravy v ISO 8601 formáte",
                  "example": "2024-01-15T10:30:00Z"
                },
                "is_active": {
                  "type": "boolean",
                  "description": "Aktívny status používateľa",
                  "example": true
                }
              }
            },
            "message": {
              "type": "string",
              "description": "Správa o úspešnom vytvorení",
              "example": "User created successfully"
            }
          }
        }
      }
    },
    "400": {
      "description": "Chybný request - neplatné vstupné dáta",
      "content": {
        "type": "application/json",
        "schema": {
          "type": "object",
          "properties": {
            "success": {
              "type": "boolean",
              "example": false
            },
            "error": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "example": "VALIDATION_ERROR"
                },
                "message": {
                  "type": "string",
                  "example": "Validation failed"
                },
                "details": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "field": {
                        "type": "string",
                        "example": "email"
                      },
                      "message": {
                        "type": "string",
                        "example": "Email is already taken"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "Neautorizovaný prístup",
      "content": {
        "type": "application/json",
        "schema": {
          "type": "object",
          "properties": {
            "success": {
              "type": "boolean",
              "example": false
            },
            "error": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "example": "UNAUTHORIZED"
                },
                "message": {
                  "type": "string",
                  "example": "Invalid or missing authentication token"
                }
              }
            }
          }
        }
      }
    },
    "409": {
      "description": "Konflikt - používateľ s daným emailom už existuje",
      "content": {
        "type": "application/json",
        "schema": {
          "type": "object",
          "properties": {
            "success": {
              "type": "boolean",
              "example": false
            },
            "error": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "example": "EMAIL_ALREADY_EXISTS"
                },
                "message": {
                  "type": "string",
                  "example": "User with this email already exists"
                }
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "Interná chyba servera",
      "content": {
        "type": "application/json",
        "schema": {
          "type": "object",
          "properties": {
            "success": {
              "type": "boolean",
              "example": false
            },
            "error": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "example": "INTERNAL_SERVER_ERROR"
                },
                "message": {
                  "type": "string",
                  "example": "An unexpected error occurred"
                }
              }
            }
          }
        }
      }
    }
  }
}

EXAMPLES

REQUEST EXAMPLE

# Basic user creation
curl -X POST https://api.example.com/api/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "email": "john.doe@example.com",
    "password": "SecurePass123!",
    "name": "John Doe"
  }'

# User with additional fields
curl -X POST https://api.example.com/api/v1/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "email": "jane.smith@example.com",
    "password": "AnotherSecure456!",
    "name": "Jane Smith",
    "role": "admin",
    "phone": "+421900987654",
    "avatar": "https://example.com/avatars/jane.jpg"
  }'

RESPONSE EXAMPLES

// Successful response (201)
{
  "success": true,
  "data": {
    "id": 12345,
    "email": "john.doe@example.com",
    "name": "John Doe",
    "role": "user",
    "phone": null,
    "avatar": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "is_active": true
  },
  "message": "User created successfully"
}

// Validation error (400)
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Email is already taken"
      },
      {
        "field": "password",
        "message": "Password must contain at least one uppercase letter"
      }
    ]
  }
}

// Unauthorized error (401)
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing authentication token"
  }
}

---

OPENAPI/SWAGGER SPECIFICATION

COMPLETE YAML SPEC

openapi: 3.0.0
info:
  title: User Management API
  description: API for managing users in the system
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server

paths:
  /users:
    post:
      tags:
        - Users
      summary: Create a new user
      description: Creates a new user in the system
      operationId: createUser
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
            examples:
              basic:
                summary: Basic user creation
                value:
                  email: "john.doe@example.com"
                  password: "SecurePass123!"
                  name: "John Doe"
              advanced:
                summary: User with all fields
                value:
                  email: "jane.smith@example.com"
                  password: "AnotherSecure456!"
                  name: "Jane Smith"
                  role: "admin"
                  phone: "+421900987654"
                  avatar: "https://example.com/avatars/jane.jpg"
      responses:
        "201":
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
              examples:
                success:
                  summary: Successful user creation
                  value:
                    success: true
                    data:
                      id: 12345
                      email: "john.doe@example.com"
                      name: "John Doe"
                      role: "user"
                      phone: null
                      avatar: null
                      created_at: "2024-01-15T10:30:00Z"
                      updated_at: "2024-01-15T10:30:00Z"
                      is_active: true
                    message: "User created successfully"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "500":
          $ref: "#/components/responses/InternalServerError"

components:
  schemas:
    CreateUserRequest:
      type: object
      required:
        - email
        - password
        - name
      properties:
        email:
          type: string
          format: email
          description: User's email address
          example: "john.doe@example.com"
        password:
          type: string
          format: password
          minLength: 8
          description: User's password
          example: "SecurePass123!"
        name:
          type: string
          description: User's name
          example: "John Doe"
        role:
          type: string
          enum: [user, admin, moderator]
          default: user
          description: User's role
          example: "user"
        phone:
          type: string
          description: User's phone number
          example: "+421900123456"
        avatar:
          type: string
          format: uri
          description: URL to user's avatar
          example: "https://example.com/avatars/john.jpg"

    UserResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: "#/components/schemas/User"
        message:
          type: string
          example: "User created successfully"

    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: User's unique ID
          example: 12345
        email:
          type: string
          format: email
          description: User's email address
          example: "john.doe@example.com"
        name:
          type: string
          description: User's name
          example: "John Doe"
        role:
          type: string
          description: User's role
          example: "user"
        phone:
          type: string
          description: User's phone number
          example: "+421900123456"
        avatar:
          type: string
          format: uri
          description: URL to user's avatar
          example: "https://example.com/avatars/john.jpg"
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
          example: "2024-01-15T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
          example: "2024-01-15T10:30:00Z"
        is_active:
          type: boolean
          description: User's active status
          example: true

    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          $ref: "#/components/schemas/ErrorDetails"

    ErrorDetails:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: "VALIDATION_ERROR"
        message:
          type: string
          description: Error message
          example: "Validation failed"
        details:
          type: array
          items:
            $ref: "#/components/schemas/ValidationErrorDetail"

    ValidationErrorDetail:
      type: object
      properties:
        field:
          type: string
          description: Field with validation error
          example: "email"
        message:
          type: string
          description: Validation error message
          example: "Email is already taken"

  responses:
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            validation:
              summary: Validation failed
              value:
                success: false
                error:
                  code: "VALIDATION_ERROR"
                  message: "Validation failed"
                  details:
                    - field: "email"
                      message: "Email is already taken"

    UnauthorizedError:
      description: Unauthorized access
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            unauthorized:
              summary: Invalid token
              value:
                success: false
                error:
                  code: "UNAUTHORIZED"
                  message: "Invalid or missing authentication token"

    ConflictError:
      description: Resource conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            conflict:
              summary: Email already exists
              value:
                success: false
                error:
                  code: "EMAIL_ALREADY_EXISTS"
                  message: "User with this email already exists"

    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            internal:
              summary: Server error
              value:
                success: false
                error:
                  code: "INTERNAL_SERVER_ERROR"
                  message: "An unexpected error occurred"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "JWT authentication token"

---

POSTMAN COLLECTION

COLLECTION JSON

{
  "info": {
    "name": "User Management API",
    "description": "Collection for testing User Management API",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "Create User",
      "request": {
        "method": "POST",
        "header": [
          {
            "key": "Content-Type",
            "value": "application/json"
          },
          {
            "key": "Authorization",
            "value": "Bearer {{jwt_token}}"
          }
        ],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"email\": \"john.doe@example.com\",\n  \"password\": \"SecurePass123!\",\n  \"name\": \"John Doe\"\n}"
        },
        "url": {
          "raw": "{{base_url}}/api/v1/users",
          "host": ["{{base_url}}"],
          "path": ["api", "v1", "users"]
        }
      },
      "response": []
    }
  ],
  "variable": [
    {
      "key": "base_url",
      "value": "https://api.example.com",
      "type": "string"
    },
    {
      "key": "jwt_token",
      "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "type": "string"
    }
  ]
}

---

BEST PRACTICES

DOCUMENTATION STANDARDS

📋 KVALITA DOKUMENTÁCIE:
□ Jasné a stručné popisy
□ Kompletné príklady použitia
□ Všetky možné chybové kódy
□ Validované príklady dát
□ Verziovanie API
□ Kontakt pre podporu

📋 TECHNICKÉ ŠTANDARDY:
□ OpenAPI/Swagger špecifikácia
□ Consistent response formáty
□ Proper HTTP status codes
□ Authentication documentation
□ Rate limiting informácie

MAINTENANCE

🔄 REGULÁRNA ÚDRŽBA:
• Týždenné: Check pre broken links
• Mesačné: Update examples
• Kvartálne: Review documentation
• Ročné: Complete audit

📝 VERZIOVANIE:
• Semantic versioning (v1.0.0, v1.1.0, v2.0.0)
• Changelog pre všetky zmeny
• Deprecation notices
• Migration guides