Skip to content
Skills Library
Programming · Writing

api-documentation

/api-documentation

Create comprehensive API documentation for developers. Use when documenting REST APIs, GraphQL schemas, or SDK methods. Handles OpenAPI/Swagger, interactive docs, examples, and API reference guides.

Licence
Apache-2.0
Last repository change
15.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
2
URLs in SKILL.md
7
Deprecation

No signals detected. Repository changed on 15.07.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

What it does and when to use it

Create comprehensive API documentation for developers. Use when documenting REST APIs, GraphQL schemas, or SDK methods. Handles OpenAPI/Swagger, interactive docs, examples, and API reference guides.

Original author description

Create comprehensive API documentation for developers. Use when documenting REST APIs, GraphQL schemas, or SDK methods. Handles OpenAPI/Swagger, interactive docs, examples, and API reference guides.

How it works

  1. When to use this skill
  2. Instructions
  3. Output format
  4. Constraints
  5. Best practices
  6. References
  7. Metadata
  8. Examples
Original SKILL.md headings · 384 lines, 847 words
SKILL.md preview
---
name: api-documentation
description: Create comprehensive API documentation for developers. Use when documenting REST APIs, GraphQL schemas, or SDK methods. Handles OpenAPI/Swagger, interactive docs, examples, and API reference guides.
metadata:
  tags: API-documentation, OpenAPI, Swagger, REST, GraphQL, developer-docs
  platforms: Claude, ChatGPT, Gemini
---


# API Documentation


## When to use this skill

- **API Development**: When adding new endpoints
- **External Release**: Public API launch
- **Team Collaboration**: Frontend-backend interface definition

## Instructions

### Step 1: OpenAPI (Swagger) Spec

```yaml
openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users
  contact:
    email: api@example.com

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

paths:
  /users:
    get:
      summary: List all users
      description: Retrieve a paginated list of users
      tags:
        - Users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      summary: Create a new user
      tags:
        - Users
      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/BadRequest'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - email
        - name

    CreateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        name:
          type: string
          minLength: 2
          maxLength: 50
        password:
          type: string
          minLength: 8
      required:
        - email
        - name
        - password

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer

  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Authentication required"

    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Invalid input"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []
```

### Step 2: Generate Documentation from Code (JSDoc/Decorators)

**Express + TypeScript**:
```typescript
/**
 * @swagger
 * /api/users:
 *   post:
 *     summary: Create a new user
 *     tags: [Users]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - email
 *               - name
 *               - password
 *             properties:
 *               email:
 *                 type: string
 *                 format: email
 *               name:
 *                 type: string
 *               password:
 *                 type: string
 *                 minLength: 8
 *     responses:
 *       201:
 *         description: User created successfully
 *       400:
 *         description: Invalid input
 */
router.post('/users', async (req, res) => {
  const { email, name, password } = req.body;
  const user = await userService.createUser({ email, name, password });
  res.status(201).json(user);
});
```

### Step 3: Interactive Documentation

**Swagger UI Setup**:
```typescript
import swaggerUi from 'swagger-ui-express';
import YAML from 'yamljs';

const swaggerDocument = YAML.load('./openapi.yaml');

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument, {
  customCss: '.swagger-ui .topbar { display: none }',
  customSiteTitle: "My API Documentation"
}));
```

### Step 4: Examples & Guides

```markdown
## API Documentation

### Authentication

All API requests require authentication using JWT tokens.

#### Getting a Token
\`\`\`bash
curl -X POST https://api.example.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "yourpassword"}'
\`\`\`

Response:
\`\`\`json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "..."
}
\`\`\`

#### Using the Token
\`\`\`bash
curl -X GET https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
\`\`\`

### Creating a User

**Endpoint**: `POST /v1/users`

**Request Body**:
\`\`\`json
{
  "email": "john@example.com",
  "name": "John Doe",
  "password": "SecurePass123!"
}
\`\`\`

**Success Response** (201):
\`\`\`json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "john@example.com",
  "name": "John Doe",
  "createdAt": "2025-01-15T10:00:00Z"
}
\`\`\`

**Error Response** (400):
\`\`\`json
{
  "error": "Email already exists"
}
\`\`\`

### Rate Limiting
- 100 requests per 15 minutes per IP
- Header: `X-RateLimit-Remaining`

### Pagination
\`\`\`
GET /v1/users?page=2&limit=20
\`\`\`

Response includes pagination info:
\`\`\`json
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 157,
    "pages": 8
  }
}
\`\`\`

### Error Codes
- `400` - Bad Request (validation error)
- `401` - Unauthorized (missing/invalid token)
- `403` - Forbidden (insufficient permissions)
- `404` - Not Found
- `409` - Conflict (duplicate resource)
- `429` - Too Many Requests (rate limit)
- `500` - Internal Server Error
```

## Output format

### API Documentation Structure

```
docs/
├── README.md                    # Overview
├── getting-started.md           # Quick start guide
├── authentication.md            # Auth guide
├── api-reference/
│   ├── users.md                 # Users endpoints
│   ├── auth.md                  # Auth endpoints
│   └── products.md              # Products endpoints
├── guides/
│   ├── pagination.md
│   ├── error-handling.md
│   └── rate-limiting.md
├── examples/
│   ├── curl.md
│   ├── javascript.md
│   └── python.md
└── openapi.yaml                 # OpenAPI spec
```

## Constraints

### Required Rules (MUST)

1. **Real Examples**: Provide working code examples
2. **Error Cases**: Document not only success but also failure cases
3. **Keep Updated**: Update documentation when API changes

### Prohibited (MUST NOT)

1. **Real Keys in Examples**: Do not use real API keys/passwords in examples
2. **Vague Descriptions**: Unclear descriptions like "returns data"

## Best practices

1. **Try It Out**: Provide interactive documentation (Swagger UI)
2. **Provide SDK**: SDK and examples for major languages
3. **Changelog**: Document API changes

## References

- [OpenAPI Specification](https://swagger.io/specification/)
- [Swagger UI](https://swagger.io/tools/swagger-ui/)
- [Redoc](https://redocly.com/)

## Metadata

### Version
- **Current Version**: 1.0.0
- **Last Updated**: 2025-01-01
- **Compatible Platforms**: Claude, ChatGPT, Gemini

### Tags
`#API-documentation` `#OpenAPI` `#Swagger` `#REST` `#developer-docs` `#documentation`

## Examples

### Example 1: Basic usage
<!-- Add example content here -->

### Example 2: Advanced usage
<!-- Add advanced example content here -->

Versions

RepositoryScoreLicence
This page · autohandai/community-skills100Apache-2.0
akillness/jeo-skills100MIT
OKHP3/skillz100MIT
drvoss/everything-copilot-cli100MIT
helx0071/skillsmo100MIT
postmanlabs/postman-plugin100Apache-2.0
LambdaTest/agent-skills100MIT
zircote-plugins/documentation-review100MIT
j4flmao/agent-skills95MIT

Identical content appears in 2 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version a16746bd4952 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95api-documentation-generator
    Generate OpenAPI/Swagger specifications and API documentation from code or design. Use when creating API docs, generating OpenAPI specs, or documenting REST APIs.
  • 100api-documenter
    API documentation specialist for OpenAPI/Swagger specifications. Use when documenting REST or GraphQL APIs.
  • 100spring-boot-openapi-documentation
    Provides patterns to generate comprehensive REST API documentation using SpringDoc OpenAPI 3.0 and Swagger UI in Spring Boot 3.x applications. Use when setting up API documentation, configuring Swagger UI, adding OpenAPI annotations, implementing security documentation, or…
  • 100openapi
    OpenAPI/Swagger specification. Covers schema definition, paths, and documentation. Use for API documentation. USE WHEN: user mentions "OpenAPI", "Swagger", "API spec", "API documentation", "schema definition", "OpenAPI 3.0", "Swagger UI", asks about "how to write OpenAPI spec",…
  • 100api-documenting
    Generate API documentation from code. Use When the user wans to document APIs, create API reference, generate endpoint documentation, or needs help with OpenAI/Swagger specs.
  • 100api-reference-documentation
    Creates professional API documentation using OpenAPI specifications with endpoints, authentication, and interactive examples. Use when documenting REST APIs, creating SDK references, or building developer portals.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.