What is generate-api-docs used for?

It creates OpenAPI/Swagger-compliant docs for current endpoints, including data models and usage examples.

When should I invoke this skill?

On explicit request to document or update APIs, especially after endpoint changes or new versions.

Can it format docs to project-specific standards?

Yes, it can output OpenAPI/Swagger or custom schemas aligned with your documentation style.

generate-api-docs

Scanned

npx machina-cli add skill gologo13/agent-skills/generate-api-docs --openclaw

Files (1)

SKILL.md

1.4 KB

Generate API Documentation

Overview

Create comprehensive API documentation for the current endpoints formatted as OpenAPI/Swagger specification or following the project's documentation standards.

Steps

API Overview
- Service description and purpose
- Base URL and versioning information
- Authentication and authorization requirements
- Rate limiting and usage policies
Endpoint Documentation
- HTTP method and URL path
- Request parameters (path, query, body)
- Request/response schemas with data types
- Example requests and responses
- Possible error codes and messages
Data Models
- Define all data models and schemas
- Include field descriptions and constraints
- Show relationships between models
- Provide example payloads
Usage Examples
- Common use case scenarios
- SDK and client library examples
- CURL command examples
- Error handling examples

API Documentation Checklist

Source

git clone https://github.com/gologo13/agent-skills/blob/main/skills/generate-api-docs/SKILL.mdView on GitHub

Overview

Generates comprehensive API documentation for the current endpoints in OpenAPI/Swagger format or project-specific standards. It covers an API overview, each endpoint with methods, paths, parameters, and error codes, plus data models and usage examples to streamline adoption and maintenance.

How This Skill Works

The skill collects the API overview (base URL, versioning, authentication, rate limits) and iterates through endpoints to capture method, path, parameters, and payload schemas. It then defines data models, adds example requests/responses, and formats everything into a standards-compliant OpenAPI/Swagger document ready for validation and distribution.

When to Use It

When API endpoints change or are extended
During onboarding of developers who need API docs
Before releasing a new API version or major update
When preparing SDKs or client libraries
To ensure docs meet project standards and validation checks

Quick Start

Step 1: Gather API overview (base URL, version, auth, rate limits)
Step 2: Document endpoints, parameters, payloads, and data models with examples
Step 3: Output to OpenAPI/Swagger, then validate and align with project standards

Best Practices

Start with a complete API overview including base URL, versioning, auth, and rate limits
Document every endpoint with method, path, parameters, and payload schemas
Define all data models with field descriptions, constraints, and relationships
Include concrete example requests, responses, and error messages
Validate the OpenAPI/Swagger output against schema validators and project standards

Example Use Cases

Documenting GET /v1/users and POST /v1/orders with full request/response examples
Defining User, Order, and ErrorResponse data models with constraints
Providing curl and SDK usage examples alongside error handling scenarios
Exporting API docs for a multi-language client library (JS, Python, Java)
Publishing versioned docs for v1 and planned v2 alongside change logs

Frequently Asked Questions

Add this skill to your agents