Openapi Spec Generation

OpenAPI Specification Generation

This skill guides the creation of OpenAPI 3.1 specifications from the API contracts defined in Phase 3, enabling SDK generation and interactive documentation.

OpenAPI 3.1 Template

See references/openapi-template.yaml for the complete OpenAPI 3.1 specification template. The template includes info block with metadata and rate limits, multiple server environments, tagged endpoints with operationIds, reusable parameters and schemas in components section, security schemes (Bearer JWT), request/response schemas, and standardized error responses.

Converting api-contracts.md to OpenAPI

Step 1: Extract Endpoints

From api-contracts.md:

### GET /users
**Response 200:**
```json
{ "data": [...], "meta": {...} }

To OpenAPI:
```yaml
paths:
  /users:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'

Step 2: Define Schemas

From response examples, create component schemas.

Step 3: Add Security

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

Validation

Using Spectral

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

Common Issues

SDK Generation

Using OpenAPI Generator

# TypeScript SDK
openapi-generator generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./sdk/typescript

# Python SDK
openapi-generator generate \
  -i openapi.yaml \
  -g python \
  -o ./sdk/python

Using Orval (TypeScript)

npm install orval
orval --config orval.config.ts

Integration with Framework Developer

During Phase 3:

1. Define API contracts in markdown
2. Convert to OpenAPI spec
3. Validate spec
4. Generate SDKs if needed
5. Store in 03-api-planning/openapi.yaml