vulkro openapi

Pro

vulkro openapi is part of Pro: Inferred OpenAPI spec (openapi), the API contract inferred from the code, with a score. On Free it stops before doing any work, prints what it needs and where to get it, and exits 1. See Pricing.

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.

Command reference

Generated from vulkro help openapi on vulkro 0.26.0. This block is the authoritative flag, usage, and exit-code reference for this command; the prose above is the friendly explanation. Do not edit this block by hand; run npm run docs:cli after a release.

[Pro] Generate an OpenAPI specification from the endpoints found in the code.

[Pro] Generate an OpenAPI 3.1 spec from vulkro's discovered endpoints. Inverse of the spec-vs-code drift check in `discover`: synthesises a spec from the code rather than comparing against an existing one.

Exit code: 0 spec written (to stdout or `--output`), 2 scan / IO error.

Usage: vulkro openapi [OPTIONS] [PATH]

Arguments:
  [PATH]
          [default: .]

Options:
  -o, --output <OUTPUT>
          

      --offline
          Hard-disable every outbound network call for this run (sets VULKRO_OFFLINE=1). Blocks the CVE feed, the license heartbeat, the update check, webhooks, and any cloud AI endpoint; a loopback model (http://127.0.0.1, http://localhost) is still allowed. Equivalent to exporting VULKRO_OFFLINE=1, and the flag wins when both are set

      --format <FORMAT>
          [default: json]
          [possible values: json, yaml]

      --project-name <PROJECT_NAME>
          

      --project-version <PROJECT_VERSION>
          

  -h, --help
          Print help (see a summary with '-h')