openapi

OpenAPI

Manage OpenAPI specifications in Phoenix apps that use open_api_spex.

Subcommands

Subcommand	Purpose
regenerate	Regenerate the OpenAPI spec from controller operations

/openapi help

Display a list of all available subcommands. Output the following exactly:

/openapi subcommands:

regenerate — Regenerate the OpenAPI spec from controller operations help — Show this help message

If `/openapi` is invoked without a subcommand, default to `regenerate`.

## Dispatch

1. Parse the subcommand from the user's invocation. Examples:
   - `/openapi` → default to `regenerate`
   - `/openapi regenerate` → subcommand `regenerate`
   - `/openapi help` → show help
2. If the subcommand is unknown, list available subcommands and stop.
3. Follow the matching workflow below.

---

## `/openapi regenerate`

Regenerate the OpenAPI specification from the app's controller operations and schema modules.

### How open_api_spex works

Phoenix apps using `open_api_spex` derive their OpenAPI spec from three sources:

1. **ApiSpec module** — implements `OpenApiSpex.OpenApi` behaviour. Defines metadata, servers, security schemes, and calls `Paths.from_router(Router)` to discover all routes.
2. **Controller operations** — each controller action declares its operation spec (parameters, request body schemas, responses) via `OpenApiSpex.operation/2` or the `OpenApiSpex.ControllerSpecs` DSL.
3. **Schema modules** — Ecto-like structs that implement `OpenApiSpex.Schema` for request/response bodies.

### Workflow

1. **Find the ApiSpec module.** Search for the module that implements `@behaviour OpenApiSpex.OpenApi`:

   ```bash
   grep -r "@behaviour OpenApiSpex.OpenApi" lib/ --include="*.ex"

It is typically named <App>Web.ApiSpec. If not found, check for @behaviour OpenApi (aliased import). If still not found, tell the user their app may not have open_api_spex set up and stop.

1. Check for existing spec files. Look for openapi.json or openapi.yaml in the project root to determine which format is in use.

2. Regenerate the spec. Run the appropriate mix task:

   For JSON:

   mix openapi.spec.json --spec <App>Web.ApiSpec
   

   For YAML:

   mix openapi.spec.yaml --spec <App>Web.ApiSpec
   

   Use whichever format already exists. If both exist, regenerate both. If neither exists, default to JSON.

3. Handle compilation errors. If the mix task fails with a compilation error:

   • Show the error to the user.
   • The spec is generated at compile time from live code — the error must be fixed in the source before the spec can be generated.
   • Offer to help fix the compilation error.

4. Verify the output. Diff the generated spec against the previous version:

   git diff openapi.json
   

   Report what changed:

   • New endpoints added
   • Endpoints removed
   • Schema changes
   • If no changes, report that the spec is already up to date.

5. Check for common issues. Warn the user about:

   • Missing operations — if a controller action lacks an OpenApiSpex.operation callback or @doc operation: annotation, its route won't appear in the spec. List any routes in the router that don't have corresponding operations in the generated spec.
   • Schema drift — if Ecto schemas were recently changed but API schema modules weren't updated, the spec may be stale. API schemas typically live alongside controllers or in a schemas/ directory.
   • Server URL — the servers field comes from Server.from_endpoint(Endpoint), which reads the endpoint config. In dev this is typically localhost:4000.

Notes

• The YAML format requires the ymlr dependency. If the user wants YAML but doesn't have ymlr, tell them to add {:ymlr, "~> 5.0"} to their deps.
• The generated spec file should be committed to version control.
• If the user has a companion CLI project (e.g., a Zig or Go client), suggest running the client's OpenAPI update command after regenerating.

$ARGUMENTS