docs_api

vuralserhat86

•

43126 months ago

Source Raw

OpenAPI/Swagger API documentation ve endpoint belgeleme şablonları.

Quick Install

npxskills add vuralserhat86/antigravity-agentic-skills--skill docs_api

Instructions

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

Loading…

Related Skills

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,360

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,309

1password

Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.

365,915

himalaya

CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).

365,885