home / skills / jeremylongshore / claude-code-plugins-plus-skills / generating-api-docs

generating-api-docs skill

safe

/plugins/api-development/api-documentation-generator/skills/generating-api-docs

This skill automates API documentation generation by outlining specs, models, endpoints, authentication, and examples to accelerate developer onboarding.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill generating-api-docs

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

2.4 KB

---
name: generating-api-docs
description: |
  Create comprehensive API documentation with examples, authentication guides, and SDKs.
  Use when creating comprehensive API documentation.
  Trigger with phrases like "generate API docs", "create API documentation", or "document the API".
  
allowed-tools: Read, Write, Edit, Grep, Glob, Bash(api:docs-*)
version: 1.0.0
author: Jeremy Longshore <[email protected]>
license: MIT
---

# Generating Api Docs

## Overview


This skill provides automated assistance for api documentation generator tasks.
This skill provides automated assistance for the described functionality.

## Prerequisites

Before using this skill, ensure you have:
- API design specifications or requirements documented
- Development environment with necessary frameworks installed
- Database or backend services accessible for integration
- Authentication and authorization strategies defined
- Testing tools and environments configured

## Instructions

1. Use Read tool to examine existing API specifications from {baseDir}/api-specs/
2. Define resource models, endpoints, and HTTP methods
3. Document request/response schemas and data types
4. Identify authentication and authorization requirements
5. Plan error handling and validation strategies
1. Generate boilerplate code using Bash(api:docs-*) with framework scaffolding
2. Implement endpoint handlers with business logic
3. Add input validation and schema enforcement
4. Integrate authentication and authorization middleware
5. Configure database connections and ORM models
1. Write integration tests covering all endpoints


See `{baseDir}/references/implementation.md` for detailed implementation guide.

## Output

- `{baseDir}/src/routes/` - Endpoint route definitions
- `{baseDir}/src/controllers/` - Business logic handlers
- `{baseDir}/src/models/` - Data models and schemas
- `{baseDir}/src/middleware/` - Authentication, validation, logging
- `{baseDir}/src/config/` - Configuration and environment variables
- OpenAPI 3.0 specification with complete endpoint definitions

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources

- Express.js and Fastify for Node.js APIs
- Flask and FastAPI for Python APIs
- Spring Boot for Java APIs
- Gin and Echo for Go APIs
- OpenAPI Specification 3.0+ for API documentation

Overview

This skill automates creation of comprehensive API documentation including OpenAPI specs, authentication guides, example requests, and SDK stubs. It streamlines turning API designs into clear, consumable docs and produces reference samples developers can use immediately. Use it to standardize docs across services and accelerate SDK generation.

How this skill works

The skill inspects your API design artifacts and extracts resource models, endpoints, HTTP methods, request/response schemas, and error cases. It generates an OpenAPI 3.0 specification, example payloads, authentication and authorization guides, and language-specific SDK samples or scaffolding. It can also produce implementation checkpoints like route definitions, controller outlines, and middleware recommendations to align docs with code.

When to use it

Creating or updating public or internal API reference documentation
Onboarding new services or standardizing documentation across teams
Preparing SDKs and example clients for multiple languages
Documenting authentication flows, error handling, and validation rules
Generating OpenAPI specs for tooling, testing, and contract validation

Best practices

Start from a clear API design or endpoint inventory to avoid guessing behavior
Document schemas with examples for success and common error responses
Include concrete authentication and authorization examples for each protected endpoint
Keep examples minimal and focused — one canonical example per operation plus a few variants
Regenerate docs as part of CI when API surface or schemas change to avoid drift

Example use cases

Produce a complete OpenAPI 3.0 spec from design notes and resource models
Generate example curl and HTTP client snippets plus SDK stubs for Python and JavaScript
Create an auth guide describing API keys, OAuth2 flows, and token refresh examples
Build error catalog and validation guidance for client teams and QA
Scaffold route and controller outlines to sync documentation with developer implementation

FAQ

Can the skill produce SDKs for multiple languages?

Yes. It generates starter SDKs and client examples for common languages such as Python and JavaScript; additional languages can be added with templates.

How does it handle authentication details?

It documents authentication and authorization requirements per endpoint and includes sample requests for API keys, OAuth2 flows, and bearer tokens to show real usage.