Openapi Spec

Name: Openapi Spec
Author: ByeongminLee

ASecurity

```yaml openapi: 3.1.0 info: title: API Name version: 1.0.0 paths: /resource: get: operationId: listResources tags: [resources] parameters: [{ $ref: '#/components/parameters/Pagination' }] responses: '200': { $ref: '#/components/responses/ResourceList' } components: schemas: {} parameters: {} responses: {} securitySchemes: {} ```

3 stars
0 votes
0 copies
4 views
Added May 27, 2026

developmenttypescriptreactnextjsapisecurity

Works with

Security analysis

A100/100

Scanned May 27, 2026

npx -y skills add ByeongminLee/nextjs-claude-code --skill openapi-spec --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Openapi Spec?

Add the live security badge to your README. It updates with every re-scan.

[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/byeongminlee-openapi-spec/badge)](https://www.skillsdirectory.com/skills/byeongminlee-openapi-spec)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro

SKILL.md

# OpenAPI 3.x Specification Patterns

## Structure
```yaml
openapi: 3.1.0
info:
  title: API Name
  version: 1.0.0
paths:
  /resource:
    get:
      operationId: listResources
      tags: [resources]
      parameters: [{ $ref: '#/components/parameters/Pagination' }]
      responses:
        '200': { $ref: '#/components/responses/ResourceList' }
components:
  schemas: {}
  parameters: {}
  responses: {}
  securitySchemes: {}
```

## Best Practices
- **operationId**: camelCase, unique per operation (`getUser`, `listOrders`)
- **Tags**: Group endpoints by domain, one primary tag per operation
- **$ref everything**: Reuse schemas, parameters, responses via `$ref`
- **Schema composition**: `allOf` for inheritance, `oneOf` for unions, `discriminator` for polymorphism
- **Pagination**: Standardize with shared parameter + response schema
- **Error responses**: Consistent `{ code: string, message: string }` schema across all errors

## Next.js API Routes
- `next-swagger-doc`: Auto-generate OpenAPI spec from JSDoc comments
- `swagger-jsdoc`: Annotate route handlers with `@openapi` blocks
- Serve spec at `/api/docs` or `/api/openapi.json`

## Code Generation
- `openapi-typescript`: Generate TypeScript types from spec
- `orval` or `openapi-codegen`: Generate API client + React Query hooks
- Validate at CI: `spectral lint openapi.yaml`

## Versioning
- URL path versioning: `/api/v1/resource` (explicit, easy to route)
- Header versioning: `Accept: application/vnd.api.v1+json` (cleaner URLs)
- Keep old versions documented until sunset date