菜单
Expert skill for OpenAPI/Swagger specification analysis, validation, and documentation generation. Parse and validate specs, detect breaking changes, generate code samples, and lint for best practices.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/a5c-ai/babysitter --skill openapi-swagger命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | openapi-swagger |
| description | Expert skill for OpenAPI/Swagger specification analysis, validation, and documentation generation. Parse and validate specs, detect breaking changes, generate code samples, and lint for best practices. |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep |
| backlog-id | SK-001 |
| metadata | {"author":"babysitter-sdk","version":"1.0.0"} |
| graph | {"domains":["domain:software-engineering"],"specializations":["specialization:technical-documentation"],"skillAreas":["skill-area:api-doc-generation","skill-area:reference-docs"],"roles":["role:technical-writer","role:documentation-engineer"]} |
Expert skill for OpenAPI/Swagger specification analysis and documentation generation.
Invoke this skill when you need to:
| Parameter | Type | Required | Description |
|---|---|---|---|
| specPath | string | Yes | Path to OpenAPI/Swagger spec file |
| action | string | Yes | validate, lint, generate-docs, diff, generate-samples |
| outputDir | string | No | Output directory for generated content |
| targetVersion | string | No | Target OpenAPI version for migration |
| languages | array | No | Languages for code sample generation |
| rulesets | array | No | Spectral ruleset files to apply |
{
"specPath": "./api/openapi.yaml",
"action": "lint",
"rulesets": [".spectral.yaml"],
"outputDir": "docs/api"
}
{
"valid": true,
"errors": [],
"warnings": [
{
"path": "paths./users.get.responses.200",
"message": "Response should have a description",
"severity": "warning"
}
],
"info": {
"title": "My API",
"version": "1.0.0",
"openApiVersion": "3.1.0"
}
}
{
"breaking": [
{
"type": "removed-endpoint",
"path": "DELETE /users/{id}",
"description": "Endpoint removed in new version"
},
{
"type": "changed-type",
"path": "POST /users.requestBody.email",
"from": "string",
"to": "object"
}
],
"nonBreaking": [
{
"type": "added-endpoint",
"path": "GET /users/{id}/profile"
}
]
}
openapi: 3.1.0
info:
title: My API
description: API description with **Markdown** support
version: 1.0.0
contact:
name: API Support
email: support@example.com
license:
name: MIT
identifier: MIT
servers:
- url: https://api.example.com/v1
description: Production
- url: https://staging-api.example.com/v1
description: Staging
tags:
- name: users
description: User management operations
paths:
/users:
get:
operationId: listUsers
summary: List all users
description: Returns a paginated list of users
tags:
- users
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/LimitParam'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
examples:
success:
$ref: '#/components/examples/UserListExample'
'401':
$ref: '#/components/responses/Unauthorized'
components:
schemas:
User:
type: object
required:
- id
- email
properties:
id:
type: string
format: uuid
description: Unique identifier
email:
type: string
format: email
description: User email address
name:
type: string
description: Display name
createdAt:
type: string
format: date-time
UserList:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
pagination:
$ref: '#/components/schemas/Pagination'
parameters:
PageParam:
name: page
in: query
schema:
type: integer
minimum: 1
default: 1
LimitParam:
name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
responses:
Unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []
extends:
- spectral:oas
rules:
# Require descriptions
operation-description: warn
operation-operationId: error
# Naming conventions
operation-operationId-valid-in-url: true
path-params: error
# Security
operation-security-defined: error
# Custom rules
path-must-have-tag:
description: Every path must have at least one tag
given: $.paths[*][*]
severity: warn
then:
field: tags
function: length
functionOptions:
min: 1
require-example:
description: Responses should have examples
given: $.paths[*][*].responses[*].content[*]
severity: info
then:
field: examples
function: truthy
// JavaScript (fetch)
const response = await fetch('https://api.example.com/v1/users', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_TOKEN',
'Content-Type': 'application/json'
}
});
const data = await response.json();
# Python (requests)
import requests
response = requests.get(
'https://api.example.com/v1/users',
headers={
'Authorization': 'Bearer YOUR_TOKEN',
'Content-Type': 'application/json'
}
)
data = response.json()
# cURL
curl -X GET 'https://api.example.com/v1/users' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json'
{
"devDependencies": {
"@stoplight/spectral-cli": "^6.11.0",
"swagger-cli": "^4.0.0",
"@redocly/cli": "^1.0.0",
"openapi-generator-cli": "^2.7.0",
"oasdiff": "^1.0.0"
}
}
# Validate spec
npx @redocly/cli lint openapi.yaml
# Spectral linting
npx spectral lint openapi.yaml
# Generate ReDoc documentation
npx @redocly/cli build-docs openapi.yaml -o docs/index.html
# Detect breaking changes
oasdiff breaking old-api.yaml new-api.yaml
# Generate code samples
npx openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o ./sdk