agentleFS
Sign inStart free
gerard-labsgerard-labs/superpowers-api-platform/skills/api-platform-openapi/SKILL.md

api-platform-openapi

Skill2 starsChanged 6 months agoMITView on GitHub

Customize API Platform 4.3 OpenAPI / Hydra / Scalar documentation — the `openapi: new \\ApiPlatform\\OpenApi\\Model\\Operation(...)` attribute (with `Info`, `Parameter`, `RequestBody`, `Response`, `Server`, `Contact`, `License`), decorating `api_platform.openapi.factory` to inject `x-logo` and global metadata, the `openapi: false` flag to hide an operation, custom OpenAPI parameters with `OpenApiParameter`, vendor extensions `x-*`, Scalar UI (`/api/docs?ui=scalar`, `enable_scalar`), Swagger UI / ReDoc, exporting the spec (`php bin/console api:openapi:export --yaml --spec-version=3.0.0 --filter-tags=public --api-gateway`), security schemes (`bearerAuth`), and ADR documentation in `docs/adr/`. **No `openapiContext`** — that belongs to `api-platform-upgrade`.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Document architectural decisions in docs/adr/ (ADR-XXXX.md).

    line 28
  2. Very specific:

    Schemas vs groups: every group affects the OpenAPI schema — use openapi_definition_name to disambiguate when needed.

    line 34

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

API Platform 4.3 — OpenAPI / Hydra / Scalar

Use when

  • Adding openapi: new Model\Operation(...) to an operation (summary, description, tags, requestBody, responses).
  • Decorating the OpenAPI factory to inject corporate Info / x-logo / Server.
  • Enabling Scalar UI on top of the default Swagger UI.
  • Hiding internal operations from the doc (openapi: false).
  • Marking operations as deprecated (Model\Operation(deprecated: true)).
  • Exporting the spec for an API Gateway or partner.

Default workflow

  1. Set global OpenAPI metadata via a factory decorator (#[AsDecorator(decorates: 'api_platform.openapi.factory')]).
  2. Per operation, attach openapi: new Model\Operation(summary, description, tags, requestBody, responses).
  3. For partner-facing endpoints, choose the UI: Swagger (default), ReDoc, Scalar (?ui=scalar).
  4. Export and review the spec (php bin/console api:openapi:export --yaml).
  5. Document architectural decisions in docs/adr/ (ADR-XXXX.md).

Guardrails

  • No openapiContext — it is deprecated. Use openapi: new Model\Operation(...).
  • Security in OpenAPI: align Model\Operation(security: [['bearerAuth' => []]]) with the global swagger.api_keys config.
  • Tags consistency: pick a short list (['Books', 'Public']) and apply it everywhere.
  • Schemas vs groups: every group affects the OpenAPI schema — use openapi_definition_name to disambiguate when needed.

Progressive disclosure

  • SKILL.md lists posture and rules.
  • reference.md carries the full attribute usage, the factory decorator, Info / Server / Contact / License, custom OpenApiParameter, vendor extensions, Scalar configuration, export commands, security schemes, ADR template.

Output contract

  • Operations carry openapi: new Model\Operation(...) (never openapiContext).
  • A factory decorator publishes corporate metadata.
  • Spec exports validated (api:openapi:export).
  • ADRs in docs/adr/ document non-trivial decisions.

References

  • reference.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free