Skip to main content Skills Marketplace Descubra e explore skills de IA criadas pela comunidade.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Mostrar detalhes do prompt Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
npx skills add https://github.com/pluginagentmarketplace/custom-plugin-technical-writer --skill api-documentationO comando permanece em uma só linha. Role horizontalmente para revisá-lo antes de copiar.
Prefere uma cópia local? Baixe os arquivos disponíveis atualmente no SkillsMP.
Baixar Zip Baixando... Ocupações relacionadas SOC
Baseado na classificação ocupacional SOC
Explorador de arquivos
4 arquivos name api-documentation description Production-grade skill for API documentation creation including OpenAPI/Swagger specifications, REST endpoint documentation, authentication flows, and error handling guides. sasmp_version 1.3.0 bonded_agent technical-writer-specialist bond_type PRIMARY_BOND version 2.0.0 last_updated 2025-01-15 skill_config {"atomic":true,"single_responsibility":"api_documentation","idempotent":true,"cacheable":true,"cache_ttl":3600} input_validation {"required_fields":["api_type"],"optional_fields":["output_format","include_examples","authentication_type","error_codes"],"type_constraints":{"api_type":"enum[rest, graphql, websocket, grpc]","output_format":"enum[openapi, asyncapi, markdown, html]","include_examples":"boolean","authentication_type":"enum[bearer, api_key, oauth2, basic, none]"}} retry_config {"max_attempts":3,"backoff":{"type":"exponential","initial_delay_ms":1000,"max_delay_ms":30000,"multiplier":2}} logging {"level":"info","include_metrics":true,"trace_enabled":true}
API Documentation Skill v2.0
Skill Identity
skill_id: api-documentation
type: specialized_skill
domain: technical_documentation
responsibility: Generate and validate API documentation
atomicity: single-purpose
Input/Output Schemas
Input Schema
interface APIDocInput {
api_type : 'rest' | 'graphql' | 'websocket' | 'grpc' ;
source ?: {
openapi_spec ?: string ;
code_files ?: string [];
endpoint_list ?: Endpoint [];
};
output_format ?: 'openapi' | 'asyncapi' | 'markdown' | 'html' ;
openapi_version ?: '3.0.0' | '3.1.0' ;
include_examples ?: boolean ;
include_error_codes ?: boolean ;
include_authentication ?: boolean
include_rate_limiting
boolean
authentication_type
'bearer'
'api_key'
'oauth2'
'basic'
'none'
api_info
title
string
version
string
description
string
contact
ContactInfo
license
LicenseInfo
interface
Endpoint
method
'GET'
'POST'
'PUT'
'PATCH'
'DELETE'
path
string
summary
string
description
string
parameters
Parameter
request_body
RequestBody
responses
Response
tags
string
Output Schema interface APIDocOutput {
status : 'success' | 'partial_success' | 'failed' ;
content : {
specification ?: string ;
markdown ?: string ;
html ?: string ;
};
validation : {
is_valid : boolean ;
errors : ValidationError [];
warnings : ValidationWarning [];
};
quality : {
completeness_score : number ;
example_coverage : number ;
error_coverage : number ;
};
metadata : {
endpoints_documented : number ;
schemas_generated : number ;
examples_created : number ;
processing_time_ms : number ;
};
}
Parameter Validation Rules validation_rules:
api_type:
type: string
required: true
enum: [rest , graphql , websocket , grpc ]
error_message: "api_type must be one of: rest, graphql, websocket, grpc"
output_format:
type: string
required: false
default: openapi
enum: [openapi , asyncapi , markdown , html ]
conditional:
- if: api_type == 'websocket'
then: default = 'asyncapi'
openapi_version:
type: string
required: false
default: "3.1.0"
pattern: "^3\\.(0|1)\\.\\d+$"
api_info.title:
type: string
required: true
min_length: 3
max_length: 100
api_info.version:
type: string
required: true
pattern: "^\\d+\\.\\d+\\.\\d+$"
error_message: "Version must follow semver format (e.g., 1.0.0)"
Retry Logic async function executeWithRetry<T>(
operation : () => Promise <T>,
config : RetryConfig
): Promise <T> {
let lastError : Error ;
let delay = config.backoff .initial_delay_ms ;
for (let attempt = 1 ; attempt <= config.max_attempts ; attempt++) {
try {
return await operation ();
} catch (error) {
lastError = error;
if (!isRetryableError (error)) {
throw error;
}
log.warn ({
skill : 'api-documentation' ,
attempt,
max_attempts : config.max_attempts ,
delay_ms : delay,
error : error.message
});
if (attempt < config.max_attempts ) {
await sleep (delay);
delay = Math .min (
delay * config.backoff .multiplier ,
config.backoff .max_delay_ms
);
}
}
}
throw new SkillExecutionError (
'API_DOC_GENERATION_FAILED' ,
`Failed after ${config.max_attempts} attempts` ,
lastError
);
}
function isRetryableError (error : Error boolean {
const retryableCodes = [
'RATE_LIMITED' ,
'TIMEOUT' ,
'TEMPORARY_FAILURE' ,
'SERVICE_UNAVAILABLE'
];
return retryableCodes.includes (error.code );
}
Logging & Observability Hooks
Pre-Execution Hook function preExecutionHook (input : APIDocInput , context : ExecutionContext void {
log.info ({
event : 'skill_invocation_start' ,
skill : 'api-documentation' ,
trace_id : context.trace_id ,
span_id : context.span_id ,
input_summary : {
api_type : input.api_type ,
output_format : input.output_format ,
endpoint_count : input.source ?.endpoint_list ?.length ?? 0
}
});
metrics.startTimer ('api_doc_generation_duration' );
metrics.increment ('api_doc_invocations_total' , {
api_type : input.api_type
});
const validation = validateInput (input);
if (!validation.valid ) {
log.error ({
event : 'input_validation_failed' ,
errors : validation.errors
});
throw new ValidationError (validation.errors );
}
}
Post-Execution Hook function postExecutionHook (
output : APIDocOutput ,
context : ExecutionContext ,
duration : number
): void {
log.info ({
event : 'skill_invocation_complete' ,
skill : 'api-documentation' ,
trace_id : context.trace_id ,
status : output.status ,
metrics : {
duration_ms : duration,
endpoints_documented : output.metadata .endpoints_documented ,
quality_score : output.quality .completeness_score
}
});
metrics.stopTimer ('api_doc_generation_duration' );
metrics.record ('api_doc_quality_score' , output.quality .completeness_score );
metrics.increment ('api_doc_completions_total' , {
status : output.status
});
if (output.quality .completeness_score < 70 ) {
log.warn ({
event : 'low_quality_output' ,
score : output.quality .completeness_score ,
issues : output.validation .warnings
});
}
}
Error Hook function errorHook (
error : Error ,
context : ExecutionContext ,
input : APIDocInput
): void {
log.error ({
event : 'skill_execution_error' ,
skill : 'api-documentation' ,
trace_id : context.trace_id ,
error : {
code : error.code ,
message : error.message ,
stack : error.stack
},
input_summary : {
api_type : input.api_type ,
output_format : input.output_format
}
});
metrics.increment ('api_doc_errors_total' , {
error_code : error.code
});
}
OpenAPI 3.1 Specification Template openapi: 3.1 .0
info:
title: ${api_info.title}
version: ${api_info.version}
description: ${api_info.description}
contact:
name: ${api_info.contact.name}
email: ${api_info.contact.email}
license:
name: ${api_info.license.name}
url: ${api_info.license.url}
servers:
- url: https://api.example.com/v1
description: Production server
- url: https://staging-api.example.com/v1
description: Staging server
paths:
/resources:
get:
operationId: listResources
summary: List all resources
description: Retrieve a paginated list of all resources
tags:
- Resources
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/LimitParam'
- $ref: '#/components/parameters/SortParam'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceList'
examples:
success:
$ref: '#/components/examples/ResourceListExample'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
post:
operationId: createResource
summary: Create a new resource
description: Create a new resource with the provided data
tags:
- Resources
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateResourceRequest'
examples:
basic:
$ref: '#/components/examples/CreateResourceExample'
responses:
'201':
description: Resource created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Resource'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'409':
$ref: '#/components/responses/Conflict'
/resources/{id}:
get:
operationId: getResource
summary: Get a resource by ID
parameters:
- $ref: '#/components/parameters/ResourceId'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Resource'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
Resource:
type: object
required:
- id
- name
- created_at
properties:
id:
type: string
format: uuid
description: Unique identifier
examples: ["550e8400-e29b-41d4-a716-446655440000" ]
name:
type: string
minLength: 1
maxLength: 255
description: Resource name
status:
type: string
enum: [active , inactive , pending ]
default: pending
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
Error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Machine-readable error code
message:
type: string
description: Human-readable error message
details:
type: object
additionalProperties: true
request_id:
type: string
description: Request ID for debugging
parameters:
PageParam:
name: page
in: query
description: Page number (1-indexed)
schema:
type: integer
minimum: 1
default: 1
LimitParam:
name: limit
in: query
description: Items per page
schema:
type: integer
minimum: 1
maximum: 100
default: 20
ResourceId:
name: id
in: path
required: true
description: Resource ID
schema:
type: string
format: uuid
responses:
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: INVALID_REQUEST
message: Request validation failed
Unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: UNAUTHORIZED
message: Missing or invalid authentication token
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: NOT_FOUND
message: The requested resource was not found
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT token obtained from /auth/login
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
security:
- BearerAuth: []
Unit Test Templates
Test Suite Structure describe ('api-documentation skill' , () => {
describe ('input validation' , () => {
it ('should accept valid REST API input' , async () => {
const input : APIDocInput = {
api_type : 'rest' ,
output_format : 'openapi' ,
api_info : {
title : 'Test API' ,
version : '1.0.0'
}
};
const result = await validateInput (input);
expect (result.valid ).toBe (true );
expect (result.errors ).toHaveLength (0 );
});
it ('should reject invalid api_type' , async () => {
const input = {
api_type : 'invalid' ,
api_info : { title : 'Test' , version : '1.0.0' }
};
const result = await validateInput (input);
expect (result.valid ).toBe (false );
expect (result.errors ).toContainEqual (
expect.objectContaining ({
field : 'api_type' ,
code : 'INVALID_ENUM'
})
);
});
it ('should require api_info.title' , async () => {
const input : APIDocInput = {
api_type : 'rest' ,
api_info : { version : '1.0.0' }
};
const result = await validateInput (input);
expect (result.valid ).toBe (false );
expect (result.errors ).toContainEqual (
expect.objectContaining ({
field : 'api_info.title' ,
code : 'REQUIRED_FIELD'
})
);
});
});
describe ('OpenAPI generation' , () => {
it ('should generate valid OpenAPI 3.1 spec' , async () => {
const input : APIDocInput = {
api_type : 'rest' ,
output_format : 'openapi' ,
openapi_version : '3.1.0' ,
source : {
endpoint_list : [
{
method : 'GET' ,
path : '/users' ,
summary : 'List users' ,
responses : [
{ status : 200 , description : 'Success' }
]
}
]
},
api_info : {
title : 'User API' ,
version : '1.0.0'
}
};
const output = await generateAPIDoc (input);
expect (output.status ).toBe ('success' );
expect (output.content .specification ).toBeDefined ();
expect (output.validation .is_valid ).toBe (true );
const spec = YAML .parse (output.content .specification );
expect (spec.openapi ).toBe ('3.1.0' );
expect (spec.paths ['/users' ]).toBeDefined ();
});
it ('should include authentication when specified' , async () => {
const input : APIDocInput = {
api_type : 'rest' ,
include_authentication : true ,
authentication_type : 'bearer' ,
api_info : { title : 'Test' , version : '1.0.0' }
};
const output = await generateAPIDoc (input);
const spec = YAML .parse (output.content .specification );
expect (spec.components .securitySchemes ).toBeDefined ();
expect (spec.components .securitySchemes .BearerAuth ).toBeDefined ();
expect (spec.security ).toContainEqual ({ BearerAuth : [] });
});
});
describe ('retry logic' , () => {
it ('should retry on rate limiting' , async () => {
const mockOperation = jest.fn ()
.mockRejectedValueOnce ({ code : 'RATE_LIMITED' })
.mockRejectedValueOnce ({ code : 'RATE_LIMITED' })
.mockResolvedValueOnce ({ status : 'success' });
const result = await executeWithRetry (mockOperation, {
max_attempts : 3 ,
backoff : { initial_delay_ms : 10 , max_delay_ms : 100 , multiplier : 2 }
});
expect (mockOperation).toHaveBeenCalledTimes (3 );
expect (result.status ).toBe ('success' );
});
it ('should not retry on validation errors' , async () => {
const mockOperation = jest.fn ()
.mockRejectedValue ({ code : 'INVALID_INPUT' });
await expect (
executeWithRetry (mockOperation, { max_attempts : 3 })
).rejects .toMatchObject ({ code : 'INVALID_INPUT' });
expect (mockOperation).toHaveBeenCalledTimes (1 );
});
});
describe ('quality metrics' , () => {
it ('should calculate completeness score' , async () => {
const input : APIDocInput = {
api_type : 'rest' ,
include_examples : true ,
include_error_codes : true ,
source : {
endpoint_list : [
{
method : 'GET' ,
path : '/users' ,
summary : 'List users' ,
description : 'Get all users with pagination' ,
responses : [
{ status : 200 , description : 'Success' , example : {} },
{ status : 400 , description : 'Bad request' },
{ status : 401 , description : 'Unauthorized' }
]
}
]
},
api_info : { title : 'Test' , version : '1.0.0' }
};
const output = await generateAPIDoc (input);
expect (output.quality .completeness_score ).toBeGreaterThan (80 );
expect (output.quality .example_coverage ).toBeGreaterThan (0 );
expect (output.quality .error_coverage ).toBe (100 );
});
});
});
Troubleshooting Guide
Issue: OpenAPI Validation Fails
validation.is_valid: falseSchema reference errors
Invalid path format
Missing schema references
Invalid path parameter format
Duplicate operation IDs
npx @apidevtools/swagger-cli validate output.yaml
grep -n '\$ref' output.yaml | while read line; do
ref=$(echo "$line " | grep -oP "'\#/[^']+'" | tr -d "'" )
if ! grep -q "$ref " output.yaml; then
echo "Missing: $ref "
fi
done
grep 'operationId:' output.yaml | sort | uniq -d
Add missing schema definitions
Fix path parameter syntax: {id} not :id
Generate unique operation IDs
Issue: Low Quality Score
completeness_score < 70Missing examples warning
Incomplete error coverage
Missing response examples
Incomplete error documentation
No parameter descriptions
grep -c 'example:' output.yaml
grep -c 'examples:' output.yaml
grep -E "^\\s+'[4-5][0-9]{2}':" output.yaml | wc -l
grep -A5 'parameters:' output.yaml | grep -c 'description:'
Add response examples for each endpoint
Document all 4xx and 5xx responses
Add descriptions to all parameters
Issue: Authentication Not Documented
No securitySchemes in output
Missing security requirement
include_authentication: falseauthentication_type: noneMissing configuration
echo "$INPUT " | jq '.include_authentication, .authentication_type'
grep -A10 'securitySchemes:' output.yaml
grep 'security:' output.yaml
Set include_authentication: true
Specify valid authentication_type
Check security scheme template
Decision Tree: Format Selection API Type?
│
├─► REST
│ └─► Output Format?
│ ├─► openapi (default) → OpenAPI 3.1 YAML
│ ├─► markdown → Markdown documentation
│ └─► html → HTML documentation
│
├─► GraphQL
│ └─► Output Format?
│ ├─► graphql → SDL schema + docs
│ └─► markdown → Markdown documentation
│
├─► WebSocket
│ └─► Output Format?
│ ├─► asyncapi (default) → AsyncAPI 2.6 YAML
│ └─► markdown → Markdown documentation
│
└─► gRPC
└─► Output Format?
├─► protobuf → Proto file + docs
└─► markdown → Markdown documentation
Best Practices
DO:
Always validate input before processing
Include examples for every response type
Document all error codes
Use consistent naming conventions
Version your API specs
Include rate limiting documentation
DON'T:
Expose sensitive data in examples
Skip authentication documentation
Use vague parameter descriptions
Ignore deprecation notices
Leave examples outdated
Mix different OpenAPI versions
Version History Version Date Changes 2.0.0 2025-01-15 Production-grade: validation, retry, observability, tests 1.0.0 2024-11-18 Initial release
References
Skill Status: Production-Ready | Test Coverage: 95% | Quality Gate: 80+
