Api Documenter

# API Documenter

> A Claude Code skill for OpenAPI/Swagger API documentation.

## Installation

This skill is part of the [agent-playbook](../../README.md) collection.

## Usage

```
You: Document this API
You: Create OpenAPI spec
You: Generate API documentation
```

## OpenAPI Specification

The skill generates OpenAPI 3.0 specifications following:
- RESTful conventions
- Clear resource naming
- Complete request/response documentation
- Authentication requirements
- Error response formats

## Scripts

Generate OpenAPI spec:
```bash
python scripts/generate_openapi.py
```

Validate OpenAPI spec:
```bash
python scripts/validate_openapi.py openapi.yaml
```

## Resources

- [OpenAPI Specification](https://swagger.io/specification/)
- [Swagger Tools](https://swagger.io/tools/)


openapi: 3.0.3
info:
  title: Sample API
  version: 0.1.0
paths:
  /health:
    get:
      responses:
        '200':
          description: OK


# OpenAPI Examples

This directory contains small OpenAPI examples for reference.


openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths: {}


#!/usr/bin/env python3
# Template generator for OpenAPI schema.

from pathlib import Path
import argparse
import textwrap


def write_output(path: Path, content: str, force: bool) -> bool:
    if path.exists() and not force:
        print(f"{path} already exists (use --force to overwrite)")
        return False
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(content, encoding="utf-8")
    return True


def main() -> int:
    parser = argparse.ArgumentParser(description="Generate a starter OpenAPI schema.")
    parser.add_argument("--output", default="openapi.yaml", help="Output file path")
    parser.add_argument("--name", default="example", help="Resource name")
    parser.add_argument("--version", default="1.0.0", help="API version")
    parser.add_argument(
        "--base-url", default="https://example.com", help="Server base URL"
    )
    parser.add_argument("--force", action="store_true", help="Overwrite existing file")
    args = parser.parse_args()

    schema_name = "".join(part.capitalize() for part in args.name.split("-"))
    if not schema_name:
        schema_name = "Example"

    content = textwrap.dedent(
        f"""\
        openapi: 3.0.3
        info:
          title: {args.name} API
          version: {args.version}
          description: API description for {args.name}
        servers:
          - url: {args.base_url}
        paths:
          /{args.name}:
            get:
              summary: List {args.name}
              responses:
                "200":
                  description: OK
                  content:
                    application/json:
                      schema:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              $ref: "#/components/schemas/{schema_name}"
        components:
          schemas:
            {schema_name}:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
          securitySchemes:
            bearerAuth:
              type: http
              scheme: bearer
        security:
          - bearerAuth: []
        """
    ).strip() + "\n"

    output = Path(args.output)
    if not write_output(output, content, args.force):
        return 1
    print(f"Wrote {output}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())


#!/usr/bin/env python3
# Template validator for OpenAPI schema.

from pathlib import Path
import argparse

DEFAULT_REQUIRED = [
    "openapi:",
    "info:",
    "servers:",
    "paths:",
    "components:",
    "securitySchemes:",
]


def main() -> int:
    parser = argparse.ArgumentParser(description="Validate a generated artifact.")
    parser.add_argument("--input", default="openapi.yam