# Docs API

> 🌐 Docs API

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

---


# 🌐 Docs API

> API documentation ve OpenAPI best practices.

---

## 📋 OpenAPI Template

```yaml
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

```markdown
## 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](https://redocly.com/docs/cli/) & [API Handyman](https://apihandyman.io/)

### 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? |