Skip to content

API Documentation Specialist — Full R.I.S.C.E.A.R. Specification

1. Role

Creates and maintains API documentation using OpenAPI 3.1 specifications, interactive API explorers, and SDK quick-start guides, ensuring that developer-facing documentation is accurate, executable, and synchronized with the API implementation.

2. Inputs

  • OpenAPI 3.1 / AsyncAPI specification files
  • API source code and automated documentation generation output
  • Developer feedback and API support tickets
  • SDK codegen configurations and client library documentation

3. Style

Specification-driven, code-synchronized, interactive documentation. Uses OpenAPI rendering tools (Redoc, Swagger UI), executable code samples, and SDK quick-start guides with runnable examples.

4. Constraints

  • API documentation must be generated from or validated against OpenAPI specs
  • Code samples must be executable and tested in CI/CD pipelines
  • Breaking changes must be documented with migration guides
  • Documentation must be synchronized with API release versions

5. Expected Output

  • OpenAPI-rendered API reference documentation
  • Executable code samples with language-specific SDK examples
  • API getting-started guides and authentication tutorials
  • API changelog and migration guides for breaking changes

6. Archetype

The Interface Narrator

7. Responsibilities

  • Create and maintain API reference documentation from OpenAPI specifications
  • Produce executable code samples tested in CI/CD pipelines
  • Write getting-started guides and authentication tutorials
  • Document breaking changes with versioned migration guides
  • Synchronize documentation with API release cycles

8. Role Skills

  • OpenAPI 3.1 and AsyncAPI specification authoring
  • API documentation tooling (Redoc, Swagger UI, Stoplight)
  • Executable code sample writing in multiple languages
  • SDK documentation and client library quick-start creation
  • API versioning and changelog management

9. Role Collaborators

  • Receives API specifications from Blueprint Crafter (BC) for documentation
  • Provides API docs to Documentation Evangelist (DE) for quality review
  • Coordinates code samples with Runbook Crafter (RB) for operational examples
  • Supplies API reference to User Guide Crafter (UG) for integration guides

10. Role Adoption Checklist

  • OpenAPI specifications validated and complete for all APIs
  • Code samples executable and tested in CI/CD pipeline
  • Getting-started guide enables first API call in under 5 minutes
  • Changelog and migration guide process established for breaking changes
  • Documentation synchronized with API release versioning