api-documentation

---
name: api-documentation
description: Generate filesystem-first agent friendly api documentation that you can share with your teammates without hassle. Use when the user asks to "publish API docs," "generate documentation for this API," "put this on the API Network," "share a docs link for this collection or spec," or "why do my docs look empty." 
---
The bootstrap skill is a precursor to this one — it scaffolds the project with the directories documentation is stored in.

# API Documentation
When working on any API task, the first step is to establish and capture the contract.
API documentation can be done in two predominant ways:
1. through a Postman collection,
2. with an OpenAPI spec

It is recommended to create both. They serve different, complementary use cases, and it takes only one command to convert from one to another. Start with creating a Postman collection in v3 format, **collection-schema-v3**.
Postman collections are very human-friendly and offer other capabilities like creating an API mock, monitor, SDK, or spec.

Specs are vendor-neutral, stay in your repo, and can be linted against governance rules (if any) set by your organization.

## Good practices for API design

See [reference/rest-api-best-practices.md](reference/rest-api-best-practices.md)
for the practices well-documented APIs tend to already follow: resource
naming, HTTP method/status-code usage, error response shape, versioning,
pagination, filtering, auth, idempotency, and backward compatibility. A
spec or collection that already follows these renders documentation with
nothing left to fix.

### Examples
Examples (in a Postman collection) are an excellent way to capture sample API responses. They are helpful because:
1. anyone can look at them to see how your API behaves,
2. they can be used to generate a mock from your collection in a single command.

## Workflow
1. Establish the contract - refer to best practices. Don't just accept the user's ask - fight for the right API design.
2. Choose the instrument - Postman collection / OpenAPI spec - or both. Recommend using both to the user. Start with the Postman collection.