1---2name: openapi-spec-writer3description: Generate comprehensive OpenAPI 3.1 specifications from API design requirements and existing endpoints4allowed-tools: [Read, Write, Bash, Grep]5effort: high6metadata:7 source: https://skillmd.com/skills/uitbreidenos/openapi-spec-writer8---910## When to activate1112- Creating OpenAPI specs for new APIs13- Documenting existing APIs from code14- Updating specs when adding new endpoints15- Generating specs from database models or route definitions16- Creating API contracts for frontend/backend alignment1718## When NOT to use1920- For GraphQL schema design (use GraphQL SDL)21- For gRPC protobuf definitions22- For WebSocket API documentation2324## Instructions25261. **Gather API requirements.** Resources, relationships, actions, and data models.272. **Define info block.** Title, version, description, contact, license, and servers (dev/staging/prod).283. **Model schemas.** Create reusable components for request/response bodies with proper types, enums, and validation rules.294. **Define paths.** Each endpoint: summary, description, parameters, request body, responses (200, 400, 401, 404, 500).305. **Add security definitions.** Auth schemes and required scopes per endpoint.316. **Include examples.** Request and response examples for every endpoint — critical for developer experience.327. **Validate spec.** Run through OpenAPI validators (spectral, swagger-cli) and fix all warnings.3334## Example3536```yaml37openapi: 3.1.038info:39 title: Users API40 version: 1.2.041 description: User management and authentication service42servers:43 - url: https://api.example.com/v144 description: Production45paths:46 /users:47 get:48 summary: List users49 parameters:50 - name: page51 in: query52 schema: { type: integer, default: 1 }53 - name: limit54 in: query55 schema: { type: integer, default: 20, maximum: 100 }56 responses:57 '200':58 description: Paginated user list59 content:60 application/json:61 schema:62 $ref: '#/components/schemas/UserListResponse'63```