pos-system/microservices/.agent/skills/documentation/references/OPENAPI.md

OpenAPI Specification Standards

This reference provides detailed guidelines for creating OpenAPI documentation for GoodGo microservices.

File Structure

docs/en/api/openapi/
├── service-name.yaml          # Main OpenAPI spec
├── schemas/                   # Reusable schemas
│   ├── common.yaml           # Common types (PaginationRequest, etc.)
│   ├── errors.yaml           # Error responses
│   └── entities.yaml         # Domain entities
└── examples/                  # Request/response examples
    ├── requests/
    └── responses/

OpenAPI Template

openapi: 3.0.3
info:
  title: Service Name API
  version: 1.0.0
  description: |
    **English**: Brief description of the service and its capabilities.
    
    **Vietnamese**: Mô tả ngắn gọn về dịch vụ và khả năng của nó.
  contact:
    name: GoodGo Platform Team
    email: dev@goodgo.vn
  license:
    name: Proprietary

servers:
  - url: https://api.goodgo.vn/v1
    description: Production
  - url: https://staging-api.goodgo.vn/v1
    description: Staging
  - url: http://localhost:5000
    description: Local development

tags:
  - name: Resources
    description: |
      **EN**: Resource management endpoints.
      **VI**: Các endpoint quản lý tài nguyên.
  - name: Admin
    description: |
      **EN**: Administrative operations (requires admin role).
      **VI**: Các thao tác quản trị (yêu cầu quyền admin).

paths:
  /resources:
    get:
      summary: List resources
      description: |
        **EN**: Retrieve a paginated list of resources with optional filtering.
        **VI**: Lấy danh sách tài nguyên có phân trang với bộ lọc tùy chọn.
      tags:
        - Resources
      parameters:
        - name: page
          in: query
          description: Page number (1-indexed) / Số trang (bắt đầu từ 1)
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          description: Items per page / Số item mỗi trang
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: search
          in: query
          description: Search keyword / Từ khóa tìm kiếm
          schema:
            type: string
      responses:
        '200':
          description: Success / Thành công
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceListResponse'
              examples:
                success:
                  $ref: '#/components/examples/ResourceListSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - bearerAuth: []

components:
  schemas:
    ResourceListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
    
    Resource:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        createdAt:
          type: string
          format: date-time
    
    PaginationMetadata:
      type: object
      properties:
        page:
          type: integer
        pageSize:
          type: integer
        totalPages:
          type: integer
        totalItems:
          type: integer
  
  responses:
    BadRequest:
      description: Bad request / Yêu cầu không hợp lệ
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    
    Unauthorized:
      description: Unauthorized / Chưa xác thực
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  
  examples:
    ResourceListSuccess:
      value:
        data:
          - id: "123e4567-e89b-12d3-a456-426614174000"
            name: "Example Resource"
            createdAt: "2024-01-18T10:00:00Z"
        pagination:
          page: 1
          pageSize: 10
          totalPages: 5
          totalItems: 42
  
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        **EN**: JWT token obtained from /auth/login endpoint.
        **VI**: JWT token lấy từ endpoint /auth/login.

Best Practices for OpenAPI

1. Use $ref for reusability: Define schemas once, reference everywhere
2. Include examples: Provide realistic request/response examples
3. Bilingual descriptions: Add both EN and VI in description fields
4. Security schemes: Document all authentication methods
5. Error responses: Define standard error response schemas
6. Validation rules: Include min/max, patterns, enums where applicable

Resources

• OpenAPI Specification - Official spec
• Redocly CLI - OpenAPI tools
• Back to Documentation Skill