openapi-conventions
Use when creating or editing an openapi.yaml for a service component — designing endpoints, request/response schemas, errors, pagination, or security for a REST API.
SKILL.mdskills/openapi-conventions/SKILL.md
GitHubOpenAPI conventions
Every service component gets one spec at
specs/design/components/<name>/openapi.yaml, authored as OpenAPI 3.0.3.
The spec is validated as it lands. A write to that path is rejected
(INVALID_OPENAPI) unless the document is OpenAPI 3.x with at least one path
and one operation, and a rejected write changes nothing. So a spec that applied
cleanly has already passed that check: do not re-validate it with a separate
tool. Handing your own spec back to a validator as pasted text costs a round
trip and re-emits the entire document — for a check that already ran.
Coverage is checklist-driven, not vibes: walk the PRD (specs/requirements/prd.md) against the
component's design.json responsibility, and give every capability the
requirements assign to THIS component its resource(s) and every core entity
its schema. A capability with no endpoint is a defect. Commonly dropped when
consolidating services: audit trail/logs, user & role management, notification
preferences, reporting/analytics — check for each explicitly before finishing.
Keep the spec COMPACT. Complete coverage, minimal prose: a short summary
per operation and a one-line description per response — no multi-sentence
descriptions, no example/examples blocks, no speculative endpoints the
requirements don't imply. Schemas carry the required fields plus the few core
properties that define the entity — not every conceivable attribute. A property
whose name and type do not give its meaning, such as a unit, a direction or a
sign, gets a one-line description in each schema that has it.
For resource taxonomy (collection/atomic/controller), URI grammar, HTTP-method
semantics, and a full worked example, read
references/wso2-rest-api-design-guidelines.md — the source of truth this
summary condenses.
Structure
servers:is relative —- url: /— never an absolute external host.- Paths are kebab-case plural nouns (
/expense-claims,/expense-claims/{claimId}/line-items); verbs only for controller actions (/expense-claims/{claimId}/submit). Max two nesting levels. - Every operation has
operationIdin lowerCamelCase verb+resource (listExpenseClaims,submitExpenseClaim) and a non-emptysummary. - Every response has a non-empty
description. Bodies areapplication/json. Reusable schemas live undercomponents/schemas.
Errors — one shared schema
Define components/schemas/Error and reference it from EVERY 4xx/5xx
response:
Error:
type: object
required: [code, message]
properties:
code: { type: integer, description: "HTTP or application error code" }
message: { type: string, description: "short human-readable label" }
description: { type: string, description: "detailed explanation" }
moreInfo: { type: string, description: "URI to documentation" }
Each operation declares at least its failure modes: '400'/'404' where
applicable, plus '401'/'403' when the API is authenticated.
Pagination — every collection GET
Parameters limit (integer, default 20, max 100) and offset (integer,
default 0). The 200 response is an envelope, not a bare array:
type: object
required: [count, data]
properties:
count: { type: integer, description: "total matching items" }
next: { type: string, nullable: true, description: "relative URI of the next page" }
previous: { type: string, nullable: true, description: "relative URI of the previous page" }
data: { type: array, items: { $ref: '#/components/schemas/ExpenseClaim' } }
Filtering and searching are query parameters on the collection GET
(?status=submitted, ?employeeId=...) — never separate endpoints.
Security
This block is the gateway's configuration, and the ONLY place the rule lives. Deploy renders one gateway route per operation from it: the audience it pins and the single scope it requires. The service holds no copy of it — a request that fails this check never reaches the service at all. Get it right here and there is nothing else to configure anywhere.
A component that depends on the sign-in resource type declares one scheme, one document-level default, and per-operation overrides:
components:
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: /oauth2/authorize
tokenUrl: /oauth2/token
scopes:
claims:read: See own claims
claims:submit: Create and send a claim
security:
- oauth2: [] # document default: any signed-in user
Every scope key, here and on an operation, is a handle from
specs/design/security.json — <resource>:<action> — for a resource THIS
component owns. Never invent one.
openid, profile, email, group and ou are reserved OIDC scopes that
ride every access token, so one of them on an operation would admit every
signed-in person in the organisation — silently, and wide open. The gate refuses
all five as an operation scope and as a flows.*.scopes key.
Three states, and only three. Each operation is exactly one of:
security on the operation |
Means | Gateway | Service |
|---|---|---|---|
| absent (inherits the document default) | any signed-in user | token required; signed assertion forwarded | 401 when the assertion is missing or does not verify |
security: [] |
public | no token checked; no assertion minted | reads no identity at all |
security: [{oauth2: ["<handle>"]}] |
that permission | scope enforced, whole-string; 401 otherwise | no scope check — a request that arrives has passed it |
The gateway answers 401 for every refusal (no token, expired, wrong
audience, missing scope) with the same body and no WWW-Authenticate. No
generated service answers 403: the only authorization question left to it is
"is this row the caller's", and that answer is 404 (api-management).
Exactly one scope per operation. No two-element list, no second scheme
object, no allOf/anyOf question for the gateway and the service to answer
differently.
Reach is the path
Which rows an operation reaches is its path, and nothing else says it:
| Path | Reaches | Guarded by |
|---|---|---|
/me/<resource> |
the caller's own rows | the resource's own-rows action — claims:read, claims:submit |
/me/<relation>/<resource> |
rows of a relation of the caller's — /me/team/claims, /me/company/orders |
its own action — claims:review-manager |
| anything else | every row | the every-row action — claims:read-all, claims:approve |
The <relation> is a noun the domain model has (team because Employee has a
managerId), never a role or a group name — /me/team/claims, not
/manager/claims. Some operation writes that relation: if none sets
managerId, /me/team/claims is empty for every caller. The handler behind a /me/… path resolves the rows through
the gateway assertion's sub and nothing the client sends; a row that is not
the caller's does not exist there, so the answer is 404, never 403.
Two consequences, both mechanical:
- One reach per handle. A handle guards operations under
/me/or outside it, never both — the same grant cannot mean "your rows" on one operation and "every row" on another. The gate refuses the document that mixes them, naming both operations. A capability with two reaches is two operations with two handles:GET /me/claimsonclaims:read,GET /claimsonclaims:read-all. - Nothing widens. There is no handler-side check that turns one list into a
bigger one. A caller who may see every claim calls
GET /claims; the SPA picks the operation for the screen, and the gateway is the whole of the decision. A role that needs both views holds both handles.
Say the reach in the operation's summary too — "The caller's claims", "Every
claim" — so a reader of the contract does not have to parse the path for it.
bearerAuth is not used on this platform. A component with no sign-in
dependency declares no security scheme at all.
Declare no identity header. The gateway hands the service the caller as a
signed x-jwt-assertion; the unsigned X-User-* headers it also sets are not
an authority and nothing reads them (api-management). Neither belongs in the
contract: the assertion is a property of the deployment, not of the API, and a
declared X-User-Id parameter invites a handler to bind one. The write gate
refuses a required: true identity header and any identity header on a public
operation; the correct document simply has none.
paths:
/me/claims:
get:
summary: "The caller's claims"
security:
- oauth2: [claims:read]
/claims:
get:
summary: "Every claim"
security:
- oauth2: [claims:read-all]
/health:
get:
security: []
Never spec an auth endpoint. No /auth/login, /auth/register,
/auth/logout, or any other token-issuance path on any service: the IDP issues
tokens and the gateway validates them (see thunder-authentication). Specifying
one puts the coding agent's issue in direct conflict with its skills.
YAML hygiene
2-space indentation throughout; quote status-code keys ('200', '404').
The file is edited with anchored string edits later, so consistent
indentation is load-bearing. Put each summary and description value in
double quotes. In a flow mapping ({ … }), a comma ends a value that has no
quotes, and the text after it becomes a new key with no value:
{ type: string, description: "e.g. submitted, approved" }.