openapi: 3.1.0
info:
  title: DeveloperHub.io API
  description: |
    REST API for the DeveloperHub.io developer documentation platform. Programmatically
    manage documentation projects, pages, versions, API references, reader access, and
    audit data. Authentication uses an X-Api-Key header generated from the DeveloperHub
    platform.
  version: "1.0.0"
  contact:
    name: DeveloperHub
    url: https://docs.developerhub.io
servers:
  - url: https://api.developerhub.io/api/v1
    description: DeveloperHub API v1
security:
  - ApiKeyAuth: []
paths:
  /documentation/{id}/page:
    post:
      summary: Create a page
      operationId: createPage
      tags: [Pages]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
          description: Documentation (section) ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PageCreate"
      responses:
        "200":
          description: Page created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Page"
  /page:
    get:
      summary: Retrieve page by slug
      operationId: getPageBySlug
      tags: [Pages]
      parameters:
        - name: slug
          in: query
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Page"
  /page/{id}:
    get:
      summary: Read page details
      operationId: getPage
      tags: [Pages]
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "200":
          description: Page
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Page" }
    put:
      summary: Update a page
      operationId: updatePage
      tags: [Pages]
      parameters:
        - $ref: "#/components/parameters/IdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PageUpdate" }
      responses:
        "200":
          description: Updated page
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Page" }
    delete:
      summary: Delete a page
      operationId: deletePage
      tags: [Pages]
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "204": { description: Deleted }
  /page/{id}/publish:
    put:
      summary: Publish a page
      operationId: publishPage
      tags: [Pages]
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "200": { description: Published }
  /version/{versionId}/documentation:
    get:
      summary: List documentation sections for a version
      operationId: listDocumentation
      tags: [Documentation]
      parameters:
        - name: versionId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Documentation sections
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Documentation" }
  /version:
    get:
      summary: List all project versions
      operationId: listVersions
      tags: [Versions]
      responses:
        "200":
          description: Versions
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Version" }
  /version/{id}:
    put:
      summary: Update a version
      operationId: updateVersion
      tags: [Versions]
      parameters:
        - $ref: "#/components/parameters/IdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/Version" }
      responses:
        "200":
          description: Updated
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Version" }
  /reference/{id}/definition:
    get:
      summary: Read API reference definition
      operationId: getReferenceDefinition
      tags: [References]
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "200":
          description: Reference definition (OpenAPI/Swagger)
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
  /reference/{id}/publish:
    put:
      summary: Publish API reference
      operationId: publishReference
      tags: [References]
      parameters:
        - $ref: "#/components/parameters/IdPath"
      responses:
        "200": { description: Published }
  /version/{versionId}/reference:
    post:
      summary: Add or update API reference for a version
      operationId: upsertReference
      tags: [References]
      parameters:
        - name: versionId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                definition: { type: object, additionalProperties: true }
      responses:
        "200":
          description: Reference saved
  /users:
    get:
      summary: Get project users and roles
      operationId: listUsers
      tags: [Project]
      responses:
        "200":
          description: User list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id: { type: string }
                    email: { type: string }
                    role: { type: string }
  /search:
    get:
      summary: Search project content
      operationId: searchContent
      tags: [Project]
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Search hits
          content:
            application/json:
              schema:
                type: object
                properties:
                  hits:
                    type: array
                    items: { type: object, additionalProperties: true }
  /all:
    get:
      summary: Retrieve all resources
      operationId: getAll
      tags: [Project]
      responses:
        "200":
          description: All resources
          content:
            application/json:
              schema: { type: object, additionalProperties: true }
  /audit:
    get:
      summary: Query audit log
      operationId: queryAudit
      tags: [Project]
      responses:
        "200":
          description: Audit entries
          content:
            application/json:
              schema:
                type: array
                items: { type: object, additionalProperties: true }
  /export:
    get:
      summary: Export project
      operationId: exportProject
      tags: [Project]
      responses:
        "200":
          description: Export bundle
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
  /reader-access:
    get:
      summary: Get invited readers
      operationId: listReaderAccess
      tags: [Reader Access]
      responses:
        "200":
          description: Readers
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    email: { type: string }
                    status: { type: string }
    post:
      summary: Grant reader access
      operationId: grantReaderAccess
      tags: [Reader Access]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email: { type: string, format: email }
      responses:
        "200": { description: Granted }
    patch:
      summary: Revoke reader access
      operationId: revokeReaderAccess
      tags: [Reader Access]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email: { type: string, format: email }
      responses:
        "200": { description: Revoked }
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      schema: { type: string }
  schemas:
    Page:
      type: object
      properties:
        id: { type: string }
        slug: { type: string }
        title: { type: string }
        content: { type: string }
        status: { type: string, enum: [draft, published] }
        versionId: { type: string }
        documentationId: { type: string }
    PageCreate:
      type: object
      required: [title]
      properties:
        title: { type: string }
        slug: { type: string }
        content: { type: string }
    PageUpdate:
      type: object
      properties:
        title: { type: string }
        slug: { type: string }
        content: { type: string }
    Version:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        isDefault: { type: boolean }
    Documentation:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        order: { type: integer }