vuralserhat86/skills/docs_api

🌐 Docs API

API documentation ve OpenAPI best practices.

📋 OpenAPI Template

openapi: 3.0.3
info:
  title: User API
  version: 1.0.0

paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id: { type: string }
        email: { type: string, format: email }

📝 Endpoint Doc Template

## Create User

`POST /api/v1/users`

### Request
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | Valid email |
| password | string | Yes | Min 8 chars |

### Response (201)
{ "success": true, "data": { "id": "...", "email": "..." } }

### Error (400)
{ "success": false, "error": { "code": "VALIDATION_ERROR" } }

Docs API v1.1 - Enhanced

🔄 Workflow

Kaynak: Redocly OpenAPI Workflow & API Handyman

Aşama 1: Design (Spec First)

• [ ] Mock: prism veya stoplight ile API'yi kodlamadan önce mockla.
• [ ] Lint: OpenAPI dosyasını spectral ile standartlara (CamelCase, Descriptions vb.) göre denetle.
• [ ] Structure: Tek devasa dosya yerine $ref kullanarak bileşenlere böl (components/schemas/User.yaml).

Aşama 2: Documentation

• [ ] Descriptions: Her endpoint ve parametre için anlamlı açıklama yaz.
• [ ] Examples: Başarılı ve hatalı (4xx, 5xx) response örneklerini mutlaka ekle.
• [ ] Auth: Security şemalarını (Bearer, OAuth2) net şekilde tanımla.

Aşama 3: Publication

• [ ] Generate: redoc-cli bundle veya swagger-cli ile statik HTML oluştur.
• [ ] Version: API versiyonunu ve değişiklik günlüğünü (Changelog) güncelle.

Kontrol Noktaları

| Aşama | Doğrulama | |-------|-----------| | 1 | spectral lint openapi.yaml hatasız geçiyor mu? | | 2 | Oluşturulan dokümantasyonda "Try it out" çalışıyor mu? | | 3 | Tüm zorunlu alanlar (required) şemada işaretli mi? |