vulkro openapi

Generate an OpenAPI 3.1 specification from your discovered endpoints. The inverse of the spec-vs-code drift check baked into vulkro discover: instead of comparing against an existing spec, this synthesises one from the code.

Usage

vulkro openapi .                            # JSON to stdout
vulkro openapi . --format yaml              # YAML to stdout
vulkro openapi . --output spec.yaml         # write to a file
vulkro openapi . \
  --project-name "Acme API" --project-version 1.4.0

Arguments

Argument	Description	Default
PATH	Project root.	.

Flags

Flag	Description	Default
--format <FMT>	json or yaml.	json
--output <FILE>, -o	Write to file instead of stdout.	stdout
--project-name <NAME>	Override info.title.	detected project name
--project-version <VER>	Override info.version.	0.1.0

What gets emitted

A standard OpenAPI 3.1 document with these mapping rules (v1 - types are not inferred, every parameter is string):

• Endpoints are grouped by path then method (lowercased). HEAD, OPTIONS, and the synthetic ANY method are skipped.
• operationId = <handler>_<method>, sanitised to alphanumeric + underscore.
• Path params (endpoint.path_params) become parameters entries with in: path, required: true, schema: { type: string }.
• Every operation gets a single 200: { description: "Success" } response.
• Endpoints whose auth_req.status == Protected get security: [{ bearerAuth: [] }]. The bearerAuth scheme is registered in components.securitySchemes unconditionally.
• Auth-model metadata surfaces as OpenAPI extensions:
  • x-vulkro-tier: admin (or user / service / machine / anonymous - Unknown is omitted).
  • x-vulkro-scopes: ["users:read", "users:write"] when non-empty.
  • x-vulkro-tenant-scoped: true when tenant_scoping == ScopedByTenant.

Example output

openapi: 3.1.0
info:
  title: Acme API
  version: 1.4.0
paths:
  /users/{id}:
    get:
      operationId: users_show_get
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
      security:
        - bearerAuth: []
      x-vulkro-tier: user
      x-vulkro-tenant-scoped: true
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

Why generate from code

• Kickstart a missing spec. Teams that don't maintain an OpenAPI spec can use Vulkro's output as the v0 contract, hand-edit from there.
• Drift recovery. When code has run ahead of the documented spec, regenerate to catch up.
• Compliance documentation. Auditors often ask for the published API surface; the generated spec is reproducible from a tagged commit.
• Pair with vulkro rbac. Same auth-tier data, two shapes - the RBAC matrix is the analyst view, the OpenAPI spec is the contract-consumer view.

Related

• vulkro discover - extracts the endpoints this command serialises.
• vulkro rbac - analyst view of the same auth data.