用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/pluginagentmarketplace/custom-plugin-api-design --skill documentation命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | documentation |
| version | 2.0.0 |
| description | API documentation with OpenAPI and developer portals |
| sasmp_version | 1.3.0 |
| bonded_agent | 08-api-documentation |
| bond_type | PRIMARY_BOND |
| atomic_design | {"single_responsibility":"API documentation generation and maintenance","boundaries":{"includes":["openapi","swagger","sdk_generation","code_examples","changelog"],"excludes":["api_design","implementation"]}} |
| parameter_validation | {"schema":{"type":"object","properties":{"format":{"type":"string","enum":["openapi","asyncapi","graphql_sdl"]},"version":{"type":"string","pattern":"^3\\.[0-1]\\.[0-9]+$"}}}} |
| retry_config | {"enabled":false} |
| logging | {"level":"INFO","fields":["doc_type","endpoints_count"]} |
| dependencies | {"skills":["api-architecture","rest","graphql"],"agents":["08-api-documentation"]} |
Create comprehensive API documentation.
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
[, ]
# 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' })
});
# 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
## [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
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');
}
});
});
});
});
| 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 |