openapi: 3.0.3
info:
  title: EasyC4 Diagram Generator API
  description: |
    HTTP API for converting PlantUML C4 or Mermaid C4 text into a diagrams.net / draw.io (.drawio) XML file.
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://c4.wtx.pl
    description: Public instance (EasyC4 Diagram Creator)

tags:
  - name: health
    description: Service check
  - name: convert
    description: Produce .drawio XML
  - name: validate
    description: Validate input without emitting XML

paths:
  /api/health:
    get:
      tags: [health]
      summary: Health check
      description: Returns whether the router is up and how many EasyC4 shapes are loaded.
      operationId: getHealth
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"

  /api/convert:
    post:
      tags: [convert]
      summary: Convert C4 source to draw.io XML
      description: |
        Parses PlantUML C4 (`@startuml` … `@enduml`) or Mermaid C4 (first line `C4Context`, `C4Container`, or `C4Component`)
        and returns a single `.drawio` document as XML.

        Send the diagram as **raw body** (`text/plain`) or wrap it in JSON (`puml` or `source` field).
      operationId: postConvert
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
              description: Full PlantUML or Mermaid C4 source
            example: |
              @startuml
              title Example
              Person(u, "User", "Uses the system")
              System(s, "System", "Does work")
              Rel(u, s, "Uses", "HTTPS")
              @enduml
          application/json:
            schema:
              $ref: "#/components/schemas/C4SourceJson"
      responses:
        "200":
          description: draw.io XML document
          headers:
            Content-Disposition:
              description: Suggested download filename (attachment)
              schema:
                type: string
                example: attachment; filename="Example.drawio"; filename*=UTF-8''Example.drawio
          content:
            application/xml:
              schema:
                type: string
                description: mxfile / draw.io XML
        "400":
          description: Parse or validation failure
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorObject"

  /api/validate:
    post:
      tags: [validate]
      summary: Validate C4 source
      description: Returns structured errors and warnings without generating XML.
      operationId: postValidate
      requestBody:
        required: true
        content:
          text/plain:
            schema:
              type: string
          application/json:
            schema:
              $ref: "#/components/schemas/C4SourceJson"
      responses:
        "200":
          description: Input is OK (may still include warnings)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidateOkResponse"
        "400":
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidateErrorResponse"

components:
  schemas:
    HealthResponse:
      type: object
      required: [ok, shapes]
      properties:
        ok:
          type: boolean
          example: true
        shapes:
          type: integer
          description: Number of loaded EasyC4 shape definitions
          example: 42

    C4SourceJson:
      type: object
      description: Either `puml` or `source` may hold the full diagram text (both names are accepted for historical reasons).
      properties:
        puml:
          type: string
        source:
          type: string

    ErrorObject:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message

    ValidateOkResponse:
      type: object
      required: [ok, errors, warnings]
      properties:
        ok:
          type: boolean
          example: true
        errors:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: string

    ValidateErrorResponse:
      type: object
      required: [ok, errors, warnings]
      properties:
        ok:
          type: boolean
          example: false
        errors:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: string
