arc-api-docs

Automatic OpenAPI 3.0 documentation generator for Arc routes.

Reads your .arc server files and emits a complete openapi.json (or YAML) spec with zero configuration.

Install

npm install arc-api-docs

Usage

CLI

# Generate openapi.json from the current project
arc-api-docs

# Specify a project directory
arc-api-docs ./my-project

# YAML output
arc-api-docs --format yaml --output openapi.yaml

# With metadata
arc-api-docs --title "My API" --api-version 2.0.0 --server https://api.example.com

Via the Arc CLI

If you have the arc CLI installed, arc docs is available out of the box:

arc docs
arc docs --format yaml --output docs/openapi.yaml

Programmatic API

const { generateDocs } = require('arc-api-docs')

const spec = await generateDocs({
  input: './my-project',      // directory containing .arc files
  title: 'My API',
  version: '1.0.0',
  output: 'openapi.json',     // write to file
  format: 'json',             // 'json' | 'yaml'
})

What gets generated

Given this Arc route file:

@group "/posts" @auth(editor)
  @route get "/posts" -> Response
    json(db.posts.findMany())

  @route get "/posts/:id" -> Response
    json(db.posts.find(params.id))

  @route post "/posts" -> Response
    const body = parseBody(request)
    json(db.posts.create(body), 201)

arc-api-docs generates:

{
  "openapi": "3.0.3",
  "info": { "title": "My API", "version": "1.0.0" },
  "paths": {
    "/posts": {
      "get": {
        "operationId": "get_posts",
        "responses": { "200": { "description": "Success" } },
        "security": [{ "bearerAuth": [] }],
        "description": "Requires role: editor"
      },
      "post": { ... }
    },
    "/posts/{id}": {
      "get": {
        "operationId": "get_posts_id",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        ...
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
    }
  }
}

Options

| Option | Default | Description | |---|---|---| | input | '.' | Directory containing .arc files | | title | from arc.config.json | API title | | version | from arc.config.json | API version | | description | — | API description | | servers | — | Array of { url, description? } server objects | | output | — | Write spec to this file path | | format | 'json' | 'json' or 'yaml' |

License

MIT