Openapi Spec

// Plugin defines topics
const char* TOPIC_CONFIG = "config";
const char* TOPIC_STATUS = "status";

void Plugin::getTopics(JsonArray& topics) const
{
    topics.add(TOPIC_CONFIG);  // Creates GET/POST /display/uid/{uid}/config
    topics.add(TOPIC_STATUS);  // Creates GET/POST /display/uid/{uid}/status
}

bool Plugin::getTopic(const String& topic, JsonObject& value) const
{
    if (topic.equals(TOPIC_CONFIG)) {
        // Handle GET request
    }
}

bool Plugin::setTopic(const String& topic, const JsonObjectConst& value)
{
    if (topic.equals(TOPIC_CONFIG)) {
        // Handle POST request
    }
}

# Find topic definitions
grep -r "TOPIC_" --include="*.cpp" --include="*.h"

# Find getTopics implementations
grep -r "getTopics" --include="*.cpp"

# Find topic handlers
grep -r "getTopic\|setTopic" --include="*.cpp"

# Find topic registration
grep -r "registerTopic" --include="*.cpp"

openapi: 3.0.3
info:
  title: [API Name]
  version: [Version from VERSION constant or git tag]
  description: [Brief API description]
  contact:
    name: [From LICENSE or README]
    email: [If available]

servers:
  - url: http://{host}/rest/api/v1
    description: REST API base path
    variables:
      host:
        default: localhost
        description: Device hostname or IP

paths:
  # Endpoints go here

components:
  schemas:
    # Reusable schemas
  responses:
    # Common responses
  securitySchemes:
    # Auth schemes

/path/{param}:
  get:
    summary: [One-line description from code comments]
    description: [Detailed behavior from docstrings/comments]
    operationId: [camelCase unique identifier]
    tags:
      - [Logical grouping]
    parameters:
      - name: param
        in: path
        required: true
        schema:
          type: string
        description: [From parameter docs]
      - name: query
        in: query
        required: false
        schema:
          type: integer
        description: [From code inspection]
    responses:
      '200':
        description: Success
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuccessResponse'
            example:
              status: "ok"
              data: {}
      '400':
        $ref: '#/components/responses/BadRequest'
      '404':
        $ref: '#/components/responses/NotFound'

components:
  schemas:
    SuccessResponse:
      type: object
      required:
        - status
        - data
      properties:
        status:
          type: string
          enum: [ok]
        data:
          type: object
          description: Endpoint-specific response data
    
    ErrorResponse:
      type: object
      required:
        - status
        - msg
      properties:
        status:
          type: string
          enum: [error]
        msg:
          type: string
          description: Human-readable error message

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication

# Then apply to protected endpoints:
paths:
  /protected:
    get:
      security:
        - basicAuth: []

# OpenAPI 3.0.3 Specification
# Generated from: [source files]
# Last updated: [date]
# See: https://swagger.io/docs/specification/v3_0/

/items:
  get:
    summary: List all items
    responses:
      '200':
        description: Array of items
  post:
    summary: Create new item
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ItemCreate'
    responses:
      '201':
        description: Item created

/items/{id}:
  get:
    summary: Get single item
  put:
    summary: Update item
  delete:
    summary: Delete item

parameters:
  - name: limit
    in: query
    schema:
      type: integer
      minimum: 1
      maximum: 100
      default: 20
  - name: offset
    in: query
    schema:
      type: integer
      minimum: 0
      default: 0

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          file:
            type: string
            format: binary
          path:
            type: string

# WRONG - assumes API uses file paths
parameters:
  - name: iconPath
    schema:
      type: string
    example: "/images/icon.bmp"

# CORRECT - API uses numeric file IDs
parameters:
  - name: iconFileId
    schema:
      type: number
    example: 1234