# Openapi

> Best practices for API documentation using OpenAPI/Swagger. Trigger: When writing OpenAPI/Swagger specifications.

- Skill: `odjaramillo/openapi` (Agent Skill)
- Install (CLI): `npx skillmds@latest add odjaramillo/openapi`
- Raw SKILL.md: https://api.skillmd.com/api/skills/odjaramillo/openapi/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: Apache-2.0
- Author: odjaramillo (https://skillmd.com/u/odjaramillo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/odjaramillo/openapi

---


## Critical Patterns

### Schema Definition (REQUIRED)

```yaml
components:
  schemas:
    User:
      type: object
      description: Represents a user in the system
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier
          example: '123e4567-e89b-12d3-a456-426614174000'
        email:
          type: string
          format: email
          description: User's email address
          example: 'user@example.com'
        name:
          type: string
          description: User's full name
          example: 'John Doe'
```

### Endpoint Documentation (REQUIRED)

```yaml
paths:
  /users/{userId}:
    get:
      summary: Get user by ID
      description: |
        Retrieves detailed information about a specific user.
        Requires authentication.
      operationId: getUserById
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: User found successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
        '401':
          description: Authentication required
```

---

## Decision Tree

```
Need reusable schema?      → Define in components/schemas
Need auth info?            → Use securitySchemes
Need examples?             → Add example field
Need multiple formats?     → Use content negotiation
Need error response?       → Define error schema
```

---

## Code Examples

### Error Response

```yaml
components:
  schemas:
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: 'USER_NOT_FOUND'
        message:
          type: string
          example: 'User with specified ID does not exist'
```

### Authentication

```yaml
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []
```

---

## Commands

```bash
# Validate spec
npx @redocly/cli lint openapi.yaml

# Generate docs
npx @redocly/cli build-docs openapi.yaml

# Generate client
npx openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
```