API Documenter

Specialist in creating comprehensive API documentation using OpenAPI/Swagger specifications.

When This Skill Activates

Activates when you:

Ask to document an API

Create OpenAPI/Swagger specs

Need API reference documentation

Mention "API docs"

OpenAPI Specification Structure

openapi

:

3.0.3

info

:

title

:

API Title

version

:

1.0.0

description

:

API description

servers

:

-

url

:

https

:

//example.com/api/v1

paths

:

/users

:

get

:

summary

:

List users

operationId

:

listUsers

tags

:

-

users

parameters

:

[

]

responses

:

'200'

:

description

:

Successful response

content

:

application/json

:

schema

:

type

:

array

items

:

$ref

:

'#/components/schemas/User'

components

:

schemas

:

User

:

type

:

object

properties

:

id

:

type

:

string

name

:

type

:

string

Endpoint Documentation

For each endpoint, document:

Required Fields

summary

Brief description

operationId

Unique identifier

description

Detailed explanation

tags

For grouping

responses

All possible responses

Recommended Fields

parameters

All parameters with details

requestBody

For POST/PUT/PATCH

security

Authentication requirements

deprecated

If applicable

Example

/users/

{

id

}

:

get

:

summary

:

Get a user by ID

operationId

:

getUserById

description

:

Retrieves a single user by their unique identifier

tags

:

-

users

parameters

:

-

name

:

id

in

:

path

required

:

true

schema

:

type

:

string

description

:

The user ID

responses

:

'200'

:

description

:

User found

content

:

application/json

:

schema

:

$ref

:

'#/components/schemas/User'

'404'

:

description

:

User not found

content

:

application/json

:

schema

:

$ref

:

'#/components/schemas/Error'

Schema Documentation

Best Practices

Use references

for shared schemas

Add descriptions

to all properties

Specify format

for strings (email, uuid, date-time)

Add examples

for complex schemas

Mark required fields

Example

components

:

schemas

:

User

:

type

:

object

required

:

-

id

-

email

properties

:

id

:

type

:

string

format

:

uuid

description

:

Unique user identifier

example

:

"550e8400-e29b-41d4-a716-446655440000"

email

:

type

:

string

format

:

email

description

:

User's email address

example

:

"user@example.com"

createdAt

:

type

:

string

format

:

date

-

time

description

:

Account creation timestamp

Authentication Documentation

Document auth requirements:

security

:

-

bearerAuth

:

[

]

components

:

securitySchemes

:

bearerAuth

:

type

:

http

scheme

:

bearer

bearerFormat

:

JWT

description

:

Use your JWT token from /auth/login

Error Responses

Standard error format:

components

:

schemas

:

Error

:

type

:

object

properties

:

error

:

type

:

string

description

:

Error message

code

:

type

:

string

description

:

Application

-

specific error code

details

:

type

:

object

description

:

Additional error details

Common HTTP status codes:

200

Success

201

Created

204

No Content

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

409

Conflict

422

Unprocessable Entity

500

Internal Server Error Scripts Generate OpenAPI spec from code: python scripts/generate_openapi.py Validate OpenAPI spec: python scripts/validate_openapi.py openapi.yaml References references/openapi-template.yaml - OpenAPI template references/examples/ - API documentation examples OpenAPI Specification