Docsalot home pagelight logo
  1. Document APIs
  2. Multiple responses

Readers should be able to see not just the happy path, but the real response shapes they will handle in production.

​
Add named examples per response

Use the examples property inside a response content block.

responses:
  "200":
    description: Documentation created
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/CreateDocumentationResponse"
        examples:
          github:
            summary: Repository-backed documentation
            value:
              id: "doc_123"
              name: "Docsalot Docs"
              provider: "github"
          local:
            summary: Local-only documentation
            value:
              id: "doc_456"
              name: "Sandbox Docs"
              provider: "filesystem"
  "409":
    description: Documentation already exists
    content:
      application/json:
        examples:
          duplicate:
            summary: Duplicate project
            value:
              error: "documentation_already_exists"

​
What to include

  • one representative success example
  • one or two meaningful failure examples
  • examples that map to conditions users actually need to branch on

​
Keep examples aligned with code

If the payload changes, update the examples in the same pull request as the schema change. Stale examples are worse than no examples because they teach the wrong contract.