Documentation
Skill pluginagentmarketplace/custom-plugin-api-design/skills/documentation
API documentation with OpenAPI and developer portalsFrom its SKILL.md
npx -y skills add pluginagentmarketplace/custom-plugin-api-design --skill documentationAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
4.2 KB, as published. Nobody here has run it
API Documentation Skill
Purpose
Create comprehensive API documentation.
OpenAPI 3.1 Structure
openapi: 3.1.0
info:
title: My API
version: 1.0.0
description: |
API description with **markdown** support.
## Authentication
Use Bearer tokens.
servers:
- url: https://api.example.com
description: Production
paths:
/users:
get:
operationId: listUsers
summary: List all users
tags: [Users]
parameters:
- $ref: '#/components/parameters/PageParam'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
components:
schemas:
User:
type: object
required: [id, name]
properties:
id:
type: string
format: uuid
name:
type: string
Code Examples
Multiple Languages
# In OpenAPI
paths:
/users:
post:
x-codeSamples:
- lang: curl
source: |
curl -X POST https://api.example.com/users \
-H "Authorization: Bearer TOKEN" \
-d '{"name": "John"}'
- lang: python
source: |
import requests
requests.post('https://api.example.com/users',
headers={'Authorization': 'Bearer TOKEN'},
json={'name': 'John'})
- lang: javascript
source: |
await fetch('https://api.example.com/users', {
method: 'POST',
headers: { 'Authorization': 'Bearer TOKEN' },
body: JSON.stringify({ name: 'John' })
});
SDK Generation
# Generate TypeScript SDK
npx @openapitools/openapi-generator-cli generate \
-i openapi.yaml \
-g typescript-fetch \
-o ./sdk
# Generate Python SDK
openapi-generator generate \
-i openapi.yaml \
-g python \
-o ./sdk-python
Changelog Format
# Changelog
## [1.2.0] - 2024-12-30
### Added
- `GET /users/export` endpoint
### Changed
- `POST /users` now returns 201
### Deprecated
- `GET /users/:id/profile` (use `/users/:id`)
### Fixed
- Pagination cursor encoding
Unit Test Template
import { validate } from '@apidevtools/swagger-parser';
describe('OpenAPI Spec', () => {
it('should be valid OpenAPI 3.1', async () => {
const api = await validate('./openapi.yaml');
expect(api.openapi).toMatch(/^3\.1\./);
});
it('should have examples for all endpoints', async () => {
const api = await validate('./openapi.yaml');
Object.values(api.paths).forEach(path => {
Object.values(path).forEach(operation => {
if (operation.responses?.['200']) {
expect(operation.responses['200'].content)
.toHaveProperty('application/json.examples');
}
});
});
});
});
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| Spec validation fails | Invalid syntax | Use spectral linter |
| SDK types wrong | Schema mismatch | Regenerate from spec |
| Missing examples | Incomplete docs | Add request/response examples |
Quality Checklist
- OpenAPI spec validates
- All endpoints documented
- Request/response examples
- Error responses documented
- Authentication explained
- SDKs generated and tested