openapi-spec
/openapi-spec
Pisze, generuje i recenzuje specyfikację OpenAPI 3.1 zgodną z implementacją: schematy, przykłady, błędy, uwierzytelnianie, paginacja, lintowanie Spectral i synchronizacja w CI.
- Autor
- khaledsaeed18 ↗
- Repozytorium
- dotclaude ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 25.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 1
Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Pisze, generuje i recenzuje specyfikację OpenAPI 3.1 zgodną z implementacją: schematy, przykłady, błędy, uwierzytelnianie, paginacja, lintowanie Spectral i synchronizacja w CI.
Argumenty
/openapi-spec (optional) the routes or handlers directory, the existing spec, or the framework
Oryginalny opis (EN)
Write, generate, or review an OpenAPI 3.1 specification for an HTTP API so that it is accurate to the implementation, complete for consumers (schemas, examples, errors, auth, pagination), and usable by tooling (validation, client generation, mock servers). Covers design-first and code-first workflows, linting with Spectral, and keeping the spec in sync in CI. Use when documenting an API, when a client generator or contract test needs a spec, or when the existing spec no longer matches the routes.
Jak działa
- Workflow
- What a complete spec has
- Design rules that show up in the spec
- Reviewing an existing spec
- Minimal skeleton
Podgląd SKILL.md
---
name: openapi-spec
description: "Write, generate, or review an OpenAPI 3.1 specification for an HTTP API so that it is accurate to the implementation, complete for consumers (schemas, examples, errors, auth, pagination), and usable by tooling (validation, client generation, mock servers). Covers design-first and code-first workflows, linting with Spectral, and keeping the spec in sync in CI. Use when documenting an API, when a client generator or contract test needs a spec, or when the existing spec no longer matches the routes."
argument-hint: "(optional) the routes or handlers directory, the existing spec, or the framework"
---
An OpenAPI document is a contract. It is worth having only if it is true, so the first question is always how it stays in sync with the code: generated from annotations or types (code-first), or validated against the implementation in CI (design-first). Pick one and make the check mechanical.
## Workflow
**Code-first** (existing API, typed framework): generate from the source of truth. NestJS (`@nestjs/swagger` decorators), FastAPI (automatic from Pydantic models), Spring (springdoc), Go (`swag`, or `huma`/`oapi-codegen` design-first), Express or Hono with zod (`zod-openapi`, `@asteasolutions/zod-to-openapi`). Commit the generated file and diff it in CI so an undocumented route change fails the build.
**Design-first** (new API, multiple implementers): write `openapi.yaml` by hand, generate server stubs and clients from it, and add a contract test (Prism mock or Dredd/Schemathesis against the running server) so the implementation cannot drift.
Either way: `spectral lint openapi.yaml` in CI with the `spectral:oas` ruleset plus house rules.
## What a complete spec has
- `info` with a real description, version (semver, bumped with breaking changes), contact.
- `servers` for each environment, with variables for the base URL.
- `securitySchemes` (bearer JWT, API key header, OAuth2 flows) and a top-level `security` default, overridden per operation where public.
- Every operation: `operationId` (unique, verbNoun, used as the client method name), `summary` (one line), `description` (when behaviour needs it), `tags` (one per resource), parameters with types, formats, constraints, and examples, request body with schema and example, every response the server can send (200/201/204, 400, 401, 403, 404, 409, 422, 429, 500) with a schema.
- One error schema used everywhere (RFC 9457 problem details: `type`, `title`, `status`, `detail`, `instance`, plus `errors[]` for validation).
- Pagination described once (cursor or page/limit) as reusable parameters and a response envelope schema.
- Schemas in `components/schemas` with `required`, `nullable` (3.1: `type: [string, "null"]`), `enum`, `format` (`date-time`, `uuid`, `email`, `uri`), `minimum`/`maxLength`, `readOnly` for server-set fields, `example` or `examples` on each.
- `deprecated: true` with a `description` saying the replacement and the removal date.
## Design rules that show up in the spec
- Resource nouns, plural, kebab-case paths: `/api/v1/order-items/{orderItemId}`.
- Ids as opaque strings (`format: uuid` when true); never expose sequential integers unless they are the public key.
- Filtering, sorting, and field selection as query parameters with documented syntax.
- Idempotency: `PUT` and `DELETE` idempotent by definition; `POST` creates take an `Idempotency-Key` header when retries are expected.
- Versioning in the path or an `Accept` header, one scheme, stated in `info.description`.
- Timestamps ISO 8601 UTC; money as integer minor units plus a currency code, never floats.
## Reviewing an existing spec
1. List the routes the code actually serves (framework route table, `grep` for the router) and diff against `paths`. Undocumented and phantom routes are the first findings.
2. For each operation, call it (or read the handler) and compare the real response shape and status codes with the spec.
3. Run `spectral lint`; fix errors, evaluate warnings.
4. Check examples validate against their schemas (`openapi-examples-validator` or Spectral's `oas3-valid-media-example`).
5. Generate a client (`openapi-generator-cli`, `openapi-typescript`) and read the output; awkward names reveal missing `operationId`s and inline schemas that should be components.
## Minimal skeleton
```yaml
openapi: 3.1.0
info: { title: Orders API, version: 1.2.0, description: ... }
servers: [{ url: https://api.example.com/v1 }]
security: [{ bearerAuth: [] }]
tags: [{ name: orders }]
paths:
/orders:
get:
operationId: listOrders
summary: List orders
tags: [orders]
parameters: [{ $ref: '#/components/parameters/Cursor' }, { $ref: '#/components/parameters/Limit' }]
responses:
'200': { description: A page of orders, content: { application/json: { schema: { $ref: '#/components/schemas/OrderPage' } } } }
'401': { $ref: '#/components/responses/Unauthorized' }
components:
securitySchemes: { bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT } }
parameters: ...
responses: ...
schemas: ...
```
Keep the file split with `$ref` to `components/` files once it passes a thousand lines, and bundle for publishing (`redocly bundle`).
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · khaledsaeed18/dotclaude | 100 | MIT |
| TerminalSkills/skills | 100 | Apache-2.0 |
Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.
Migawka bazy z 13.11.2026 · wersja paczki bba8d1ea3e51 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100openapi-spec-generator
Prawdopodobnie generuje specyfikacje OpenAPI dla interfejsów API i pomaga w budowaniu integracji. - 100openapi-spec-authoring
Pisze i sprawdza specyfikacje OpenAPI 3.1 z modelami JSON Schema i spójnym modelem błędów RFC 9457. - 100api-docs-writer
Pisze precyzyjną dokumentację referencyjną API HTTP i specyfikacje OpenAPI 3.1: strony endpointów, schematy, parametry, uwierzytelnianie, paginacja, przykłady kodu i tabele błędów. - 100openapi-spec-generation
Tworzy i aktualizuje specyfikacje OpenAPI 3.1 na podstawie kodu lub projektu pisanego przed implementacją oraz wzorców walidacji, przy dokumentacji API i generowaniu SDK. - 100openapi-generate
Generuje specyfikacje OpenAPI 3.1 z istniejącego kodu (trasy, kontrolery, typy, schematy Zod i Joi) albo kod ze specyfikacji, w tym klienty SDK, serwery mock i kolekcje Postman. - 100rc-openapi
Tworzy lub aktualizuje specyfikację OpenAPI, odkrywając z kodu endpointy HTTP, schematy żądań i modele odpowiedzi, i utrzymuje openapi.yaml zgodny ze zmianami API.