Skip to the rows

agentsclimarketplace

Api documentation

Skill yigityildiz0/universal-ai-skill-library/skills/common/api-documentation

531 searchable AI Agent Skills for Claude Code, OpenAI Codex, and OpenCode — EN/TR catalog, platform and risk notes, direct ZIPs, and curated bundles.

Install

npx -y skills add yigityildiz0/universal-ai-skill-library --skill api-documentation

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

3 things to look at

18 days oldThe repository was created 18 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Create OpenAPI/Swagger specifications, API reference documentation, endpoint descriptions, and usage examples. Use when documenting REST APIs, GraphQL.

SKILL.md

15.6 KB, as published. Nobody here has run it

API Documentation

Create complete, accurate API documentation that enables developers to quickly understand and successfully integrate with your API.

When to Use This Skill

Use this skill when you need to:

Document REST API endpoints
Create OpenAPI/Swagger specifications
Write API reference documentation
Document GraphQL schemas
Add request/response examples
Document authentication flows

Trigger phrases: "API documentation", "OpenAPI spec", "Swagger", "endpoint documentation", "API reference", "REST docs"

What This Skill Does

Documentation Components

OpenAPI Specification - Machine-readable API definition
Endpoint Reference - Complete endpoint documentation
Authentication Guide - Auth flows and examples
Error Reference - Error codes and handling
Code Examples - Working examples in multiple languages
Rate Limiting - Usage limits and best practices

Instructions

OpenAPI 3.0 Specification

openapi: 3.0.3
info:
  title: User Management API
  description: |
    API for managing users, authentication, and profiles.

    ## Authentication
    All endpoints require Bearer token authentication.
    Obtain tokens via `/auth/login`.

    ## Rate Limiting
    - Standard: 100 requests/minute
    - Authenticated: 1000 requests/minute
  version: 1.0.0
  contact:
    name: API Support
    email: [email protected]
    url: https://example.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging
  - url: http://localhost:8000/v1
    description: Development

tags:
  - name: Authentication
    description: User authentication and token management
  - name: Users
    description: User CRUD operations
  - name: Profiles
    description: User profile management

paths:
  /auth/login:
    post:
      tags:
        - Authentication
      summary: Authenticate user
      description: |
        Authenticate with email and password to receive access token.
        Tokens expire after 24 hours.
      operationId: login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            example:
              email: [email protected]
              password: securePassword123
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
              example:
                token: eyJhbGciOiJIUzI1NiIs...
                expires_at: "2025-01-16T10:30:00Z"
                user:
                  id: "550e8400-e29b-41d4-a716-446655440000"
                  email: [email protected]
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '429':
          $ref: '#/components/responses/RateLimitError'

  /users:
    get:
      tags:
        - Users
      summary: List users
      description: Retrieve paginated list of users
      operationId: listUsers
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          description: Page number (1-indexed)
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          description: Items per page
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: sort
          in: query
          description: Sort field
          schema:
            type: string
            enum: [created_at, email, name]
            default: created_at
        - name: order
          in: query
          description: Sort order
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

    post:
      tags:
        - Users
      summary: Create user
      description: Create a new user account
      operationId: createUser
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/ValidationError'
        '409':
          description: Email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/{userId}:
    get:
      tags:
        - Users
      summary: Get user by ID
      operationId: getUser
      security:
        - bearerAuth: []
      parameters:
        - name: userId
          in: path
          required: true
          description: User UUID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFoundError'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from /auth/login

  schemas:
    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          description: User email address
        password:
          type: string
          format: password
          minLength: 8
          description: User password

    AuthResponse:
      type: object
      properties:
        token:
          type: string
          description: JWT access token
        expires_at:
          type: string
          format: date-time
          description: Token expiration timestamp
        user:
          $ref: '#/components/schemas/User'

    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique user identifier
        email:
          type: string
          format: email
        name:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateUserRequest:
      type: object
      required:
        - email
        - password
        - name
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
          minLength: 8
        name:
          type: string
          minLength: 1
          maxLength: 100

    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable message
        details:
          type: object
          description: Additional error details

  responses:
    UnauthorizedError:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: UNAUTHORIZED
            message: Authentication required

    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    ValidationError:
      description: Validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    RateLimitError:
      description: Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Request limit per minute
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Remaining requests
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix timestamp when limit resets
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

API Reference Documentation

# API Reference

## Authentication

### Login

Authenticate with email and password to obtain an access token.

**Endpoint:** `POST /auth/login`

**Request Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | User email address |
| password | string | Yes | User password (min 8 chars) |

**Response:**

```json
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2025-01-16T10:30:00Z",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "name": "John Doe"
  }
}

Example:

curl -X POST https://api.example.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "securePassword123"}'

Errors:

Code	Status	Description
INVALID_CREDENTIALS	401	Email or password incorrect
ACCOUNT_LOCKED	403	Too many failed attempts
RATE_LIMITED	429	Too many requests

Users

List Users

Retrieve a paginated list of users.

Endpoint: GET /users

Authentication: Required (Bearer token)

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max 100)
sort	string	created_at	Sort field
order	string	desc	Sort order (asc/desc)

Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "[email protected]",
      "name": "John Doe",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}

Example:

curl https://api.example.com/v1/users?page=1&limit=10 \
  -H "Authorization: Bearer YOUR_TOKEN"


### Code Examples Template

```markdown
# Code Examples

## Python

```python
import requests

BASE_URL = "https://api.example.com/v1"

# Authenticate
response = requests.post(f"{BASE_URL}/auth/login", json={
    "email": "[email protected]",
    "password": "securePassword123"
})
token = response.json()["token"]

# Create headers
headers = {"Authorization": f"Bearer {token}"}

# Get users
users = requests.get(f"{BASE_URL}/users", headers=headers)
print(users.json())

# Create user
new_user = requests.post(f"{BASE_URL}/users", headers=headers, json={
    "email": "[email protected]",
    "password": "newPassword123",
    "name": "New User"
})
print(new_user.json())

JavaScript (Node.js)

const axios = require('axios');

const BASE_URL = 'https://api.example.com/v1';

async function main() {
  // Authenticate
  const auth = await axios.post(`${BASE_URL}/auth/login`, {
    email: '[email protected]',
    password: 'securePassword123'
  });
  const token = auth.data.token;

  // Configure client
  const client = axios.create({
    baseURL: BASE_URL,
    headers: { Authorization: `Bearer ${token}` }
  });

  // Get users
  const users = await client.get('/users');
  console.log(users.data);

  // Create user
  const newUser = await client.post('/users', {
    email: '[email protected]',
    password: 'newPassword123',
    name: 'New User'
  });
  console.log(newUser.data);
}

main();

cURL

# Authenticate
TOKEN=$(curl -s -X POST https://api.example.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "securePassword123"}' \
  | jq -r '.token')

# Get users
curl https://api.example.com/v1/users \
  -H "Authorization: Bearer $TOKEN"

# Create user
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "pass123", "name": "New"}'


### Error Reference Template

```markdown
# Error Reference

## Error Response Format

All errors follow this structure:

```json
{
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "details": {
    "field": "Additional context"
  }
}

Error Codes

Authentication Errors (4xx)

Code	HTTP Status	Description	Resolution
`UNAUTHORIZED`	401	Missing or invalid token	Include valid Bearer token
`INVALID_CREDENTIALS`	401	Wrong email/password	Check credentials
`TOKEN_EXPIRED`	401	Token has expired	Re-authenticate
`FORBIDDEN`	403	Insufficient permissions	Check user role
`ACCOUNT_LOCKED`	403	Too many failed attempts	Wait or contact support

Validation Errors (400)

Code	HTTP Status	Description	Resolution
`VALIDATION_ERROR`	400	Request validation failed	Check `details` field
`INVALID_EMAIL`	400	Email format invalid	Use valid email
`WEAK_PASSWORD`	400	Password too weak	Use 8+ chars with complexity

Resource Errors (4xx)

Code	HTTP Status	Description	Resolution
`NOT_FOUND`	404	Resource doesn't exist	Check ID
`CONFLICT`	409	Resource already exists	Use different identifier

Rate Limiting (429)

Code	HTTP Status	Description	Resolution
`RATE_LIMITED`	429	Too many requests	Wait and retry with backoff

Rate Limit Headers:

X-RateLimit-Limit: Max requests per window
X-RateLimit-Remaining: Requests remaining
X-RateLimit-Reset: Unix timestamp of reset

Server Errors (5xx)

Code	HTTP Status	Description	Resolution
`INTERNAL_ERROR`	500	Server error	Retry later, contact support
`SERVICE_UNAVAILABLE`	503	Maintenance	Retry later


## Tools

- **Swagger UI**: Interactive documentation
- **Redoc**: Beautiful API docs
- **Stoplight**: API design platform
- **Postman**: API testing and docs
- **OpenAPI Generator**: Client generation

## Quality Checklist

- [ ] All endpoints documented
- [ ] Request/response schemas complete
- [ ] Authentication documented
- [ ] Error codes comprehensive
- [ ] Examples work correctly
- [ ] Rate limits documented
- [ ] Versioning explained
- [ ] OpenAPI spec valid
- [ ] SDK examples provided
- [ ] Changelog maintained

## Related Skills

- `docstrings` - Code documentation
- `technical-documentation` - Architecture docs
- `user-documentation` - User guides

---

**Version**: 1.0.0
**Last Updated**: December 2025
**Based on**: AI Templates documentation_generation/api_docs/


### Iterative Refinement Strategy
This skill is optimized for an iterative approach:
1. **Execute**: Perform the core steps defined above.
2. **Review**: Critically analyze the output (coverage, quality, completeness).
3. **Refine**: If targets aren't met, repeat the specific implementation steps with improved context.
4. **Loop**: Continue until the definition of done is satisfied.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.