📖 API Documentation System¶

🎯 Overview¶

The API Documentation System automatically generates comprehensive OpenAPI/Swagger documentation for all Continuum APIs. Every time a collection is created or modified, the documentation is automatically updated, providing an always-current, interactive API reference.

📋 Purpose¶

The API Documentation System provides: - Automatic Generation: OpenAPI 3.0 specifications generated from schema - Interactive Interface: Swagger UI for testing APIs directly - Real-Time Updates: Documentation syncs with schema changes - Per-Collection Docs: Separate documentation for each collection - API Discovery: Browse all available endpoints and schemas

🏗️ Architecture¶

graph TB
    Schema[Collection Schema]

    subgraph "Documentation Generator"
        Analyzer[Schema Analyzer]
        OpenAPIGen[OpenAPI Generator]
        SwaggerUI[Swagger UI]
    end

    subgraph "Documentation Endpoints"
        GetURLs[Get URLs Endpoint]
        GetSpec[Get Specification]
        CoreDocs[Core API Docs]
        CollectionDocs[Collection Docs]
    end

    subgraph "Outputs"
        Interactive[Interactive UI]
        JSONSpec[JSON Specification]
        YAMLSpec[YAML Specification]
    end

    Schema --> Analyzer
    Analyzer --> OpenAPIGen

    OpenAPIGen --> GetURLs
    OpenAPIGen --> GetSpec
    OpenAPIGen --> CoreDocs
    OpenAPIGen --> CollectionDocs

    GetSpec --> SwaggerUI
    SwaggerUI --> Interactive

    GetSpec --> JSONSpec
    GetSpec --> YAMLSpec

    classDef generator fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef endpoint fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    classDef output fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px

    class Analyzer,OpenAPIGen,SwaggerUI generator
    class GetURLs,GetSpec,CoreDocs,CollectionDocs endpoint
    class Interactive,JSONSpec,YAMLSpec output

🌐 Accessing Documentation¶

📋 Interactive Swagger UI¶

Access the interactive documentation at:

https://your-domain.com/admin/settings/api-doc/documentation

Features: - ✅ Browse all available endpoints - ✅ View request/response schemas - ✅ Test APIs directly from browser - ✅ See example requests and responses - ✅ View authentication requirements

📡 API Endpoints¶

Get Available Documentation URLs¶

GET /api/swagger:getUrls
X-App: main
Authorization: Bearer {api-key}

Response:

{
  "data": [
    {
      "name": "Core API",
      "url": "/api/swagger:get?ns=core"
    },
    {
      "name": "Collections API",
      "url": "/api/swagger:get?ns=collections"
    },
    {
      "name": "Articles Collection",
      "url": "/api/swagger:get?ns=collections/articles"
    },
    {
      "name": "Users Collection",
      "url": "/api/swagger:get?ns=collections/users"
    }
  ]
}

Get Complete Documentation¶

GET /api/swagger:get
X-App: main
Authorization: Bearer {api-key}

Returns complete OpenAPI 3.0 specification for all APIs.

Get Core API Documentation¶

GET /api/swagger:get?ns=core
X-App: main
Authorization: Bearer {api-key}

Returns documentation for core system APIs (collections, fields, applications, etc.).

Get Collection-Specific Documentation¶

GET /api/swagger:get?ns=collections/articles
X-App: main
Authorization: Bearer {api-key}

Returns documentation for a specific collection's CRUD APIs.

📄 OpenAPI Specification¶

🏗️ Generated Structure¶

openapi: 3.0.0
info:
  title: Continuum API
  version: 1.0.0
  description: API documentation for Continuum MAAAS platform

servers:
  - url: https://your-domain.com/api
    description: Production server

security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    # Auto-generated from collections
    Article:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        content:
          type: string
        # ... more fields

    # List response wrapper
    ArticleListResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            count:
              type: integer
            rows:
              type: array
              items:
                $ref: '#/components/schemas/Article'

paths:
  /articles:list:
    get:
      summary: List articles
      tags:
        - Articles
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Sort'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticleListResponse'

🔑 Schema Components¶

Each collection automatically generates:

1️⃣ Model Schema¶

{
  "Article": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "description": "Unique identifier"
      },
      "title": {
        "type": "string",
        "description": "Article title"
      },
      "status": {
        "type": "string",
        "enum": ["draft", "published", "archived"],
        "default": "draft"
      },
      "author": {
        "$ref": "#/components/schemas/User"
      }
    },
    "required": ["title"]
  }
}

2️⃣ Request/Response Schemas¶

{
  "ArticleCreateRequest": {
    "type": "object",
    "properties": {
      "title": {"type": "string"},
      "content": {"type": "string"}
    }
  },
  "ArticleResponse": {
    "type": "object",
    "properties": {
      "data": {
        "$ref": "#/components/schemas/Article"
      }
    }
  }
}

3️⃣ Relationship Schemas¶

{
  "ArticleWithRelations": {
    "allOf": [
      {"$ref": "#/components/schemas/Article"},
      {
        "type": "object",
        "properties": {
          "author": {
            "$ref": "#/components/schemas/User"
          },
          "comments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Comment"
            }
          }
        }
      }
    ]
  }
}

🎯 Using Swagger UI¶

📋 Testing APIs¶

1. Navigate to Swagger UI: https://your-domain.com/admin/settings/api-doc/documentation

2. Authorize:

3. Click "Authorize" button
4. Enter your API key: Bearer {your-api-key}

5. Click "Authorize" then "Close"

6. Select Endpoint:

7. Browse collections on left sidebar

8. Click on the endpoint you want to test

9. Try It Out:

10. Click "Try it out" button
11. Fill in parameters and request body

12. Click "Execute"

13. View Results:

14. See actual request sent
15. View response code and body
16. Check response headers

📝 Example Workflow¶

Testing Article Creation:

1. Find POST /articles:create endpoint
2. Click "Try it out"
3. Enter request body:

   {
     "title": "Test Article",
     "content": "This is a test",
     "status": "draft"
   }
   

4. Click "Execute"
5. View response:

   {
     "data": {
       "id": 42,
       "title": "Test Article",
       "content": "This is a test",
       "status": "draft",
       "createdAt": "2025-01-20T14:30:00Z"
     }
   }
   

🔧 Customizing Documentation¶

📋 Collection Descriptions¶

Add descriptions when creating collections:

POST /api/collections:create
X-App: main
Content-Type: application/json

{
  "name": "articles",
  "title": "Articles",
  "description": "Blog articles and content pieces",
  "fields": [...]
}

Appears in Swagger UI as collection description.

🏷️ Field Descriptions¶

Add descriptions to fields:

POST /api/fields:create
X-App: main
Content-Type: application/json

{
  "collectionName": "articles",
  "name": "title",
  "type": "string",
  "description": "The main title of the article"
}

📝 UI Schema Hints¶

Provide UI hints for better documentation:

{
  "name": "status",
  "type": "string",
  "uiSchema": {
    "title": "Publication Status",
    "enum": [
      {"label": "Draft", "value": "draft"},
      {"label": "Published", "value": "published"},
      {"label": "Archived", "value": "archived"}
    ]
  }
}

📊 Documentation Features¶

🔍 Search Functionality¶

Swagger UI includes built-in search: - Search by endpoint path - Search by tag/collection name - Search within descriptions

🏷️ Tagging & Organization¶

Endpoints are automatically organized by: - Collection Name: All endpoints for a collection grouped together - Operation Type: Create, Read, Update, Delete - Resource Type: Core APIs vs Collection APIs

📝 Examples¶

Auto-generated examples include: - Request Examples: Sample JSON for create/update operations - Response Examples: Expected response structures - Parameter Examples: Valid query parameter values - Error Examples: Common error responses

🔗 Relationship Documentation¶

Relationship endpoints are fully documented:

/articles/{id}/comments:list:
  get:
    summary: List comments for an article
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    responses:
      '200':
        description: Success
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/Comment'

💡 Best Practices¶

📝 Documentation Quality¶

DO: - ✅ Add clear descriptions to collections - ✅ Document field purposes - ✅ Provide example values - ✅ Keep documentation in sync with schema - ✅ Use consistent terminology

DON'T: - ❌ Leave descriptions empty - ❌ Use technical jargon without explanation - ❌ Forget to update after schema changes - ❌ Skip documenting relationships

🎯 API Design¶

DO: - ✅ Design consistent endpoint patterns - ✅ Use descriptive collection names - ✅ Follow REST conventions - ✅ Provide clear error messages - ✅ Version your APIs

DON'T: - ❌ Create overly complex endpoints - ❌ Use inconsistent naming - ❌ Expose internal implementation details - ❌ Skip input validation

🔌 External Tools Integration¶

📦 Postman¶

Import OpenAPI specification into Postman:

1. Get Specification:

   curl 'https://your-domain.com/api/swagger:get' \
     -H 'X-App: main' \
     -H 'Authorization: Bearer {api-key}' \
     > continuum-api.json
   

2. Import to Postman:

3. Open Postman
4. File → Import
5. Select continuum-api.json
6. All endpoints imported as collection

🔧 Insomnia¶

Similar process for Insomnia REST client:

1. Export OpenAPI spec
2. Import → From File
3. Select exported JSON/YAML

💻 Code Generation¶

Use OpenAPI generators to create client SDKs:

# Generate TypeScript SDK
openapi-generator-cli generate \
  -i continuum-api.json \
  -g typescript-fetch \
  -o ./generated-sdk

# Generate Python SDK
openapi-generator-cli generate \
  -i continuum-api.json \
  -g python \
  -o ./generated-sdk

🔗 Related Documentation¶

• API Gateway: Overall API architecture
• Collection Manager: Schema that drives documentation
• Authentication: Security schemes in documentation
• Best Practices: API design guidelines

Note: The auto-generated documentation ensures that your API reference is always accurate and up-to-date with minimal effort.