菜单
Generate complete, production-ready OpenAPI 3.x and Swagger 2.0 specifications from natural language descriptions, code, or partial specs. Use this skill whenever the user mentions OpenAPI, Swagger, API spec, REST API documentation, YAML/JSON API schema, endpoint documentation, API...
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/ChonSong/skill-retriever --skill openapi-spec-generator命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | openapi-spec-generator |
| description | Generate complete, production-ready OpenAPI 3.x and Swagger 2.0 specifications from natural language descriptions, code, or partial specs. Use this skill whenever the user mentions OpenAPI, Swagger, API spec, REST API documentation, YAML/JSON API schema, endpoint documentation, API... |
| risk | unknown |
| source | https://github.com/LambdaTest/agent-skills/tree/main/api-skill/openapi-spec-generator |
| source_repo | LambdaTest/agent-skills |
| source_type | community |
| date_added | 2026-07-01T00:00:00.000Z |
| license | MIT |
| license_source | https://github.com/LambdaTest/agent-skills/blob/main/LICENSE |
Use this skill when you need generate complete, production-ready OpenAPI 3.x and Swagger 2.0 specifications from natural language descriptions, code, or partial specs. Use this skill whenever the user mentions OpenAPI, Swagger, API spec, REST API documentation, YAML/JSON API schema, endpoint documentation, API...
Generate complete, valid OpenAPI 3.x or Swagger 2.0 specifications from descriptions, code, or partial specs.
Before writing any YAML/JSON, ask (or infer from context) the following:
| Question | Why it matters |
|---|---|
| OpenAPI 3.x or Swagger 2.0? | Different info, servers/host, components/definitions structure |
| Output format: YAML or JSON? | YAML default unless user specifies JSON |
| What does this API do? | Sets info.title, info.description, tags |
| List of endpoints (or code to extract from)? | Core paths object |
| Authentication type(s)? | securitySchemes — see reference |
| Common data models or entities? | components/schemas / definitions |
| Any existing partial spec to extend? | Merge rather than overwrite |
If the user provides code (Express routes, FastAPI, Django URLs, Spring controllers, etc.), extract endpoints automatically — do not ask what the user already told you.
Follow the structure guide for the chosen version. Always produce a complete, valid spec — never leave placeholder comments like # TODO: add schema.
openapi: "3.1.0"
info:
title: <API Title>
version: "1.0.0"
description: <Short
[]
[]
[]
[]
{}
{}
swagger: "2.0"
info:
title: <API Title>
version: "1.0.0"
description: <Short description>
host: api.example.com
basePath: /v1
schemes: [https]
consumes: [application/json]
produces: [application/json]
tags: []
paths: {}
definitions: {}
securityDefinitions: {}
$ref for any schema used in more than one place.example or examples on every schema and response body.required array.nullable: true (OAS 3.0) or x-nullable: true (Swagger 2.0) for optional nullable fields.format keywords: int32, int64, float, date, date-time, uuid, email, uri, byte, binary.Common schema patterns:
# Pagination wrapper
PagedResult:
type: object
required: [items, total, page, pageSize]
properties:
items:
type: array
items:
$ref: "#/components/schemas/Resource"
total:
type: integer
format: int64
example: 100
page:
type: integer
format: int32
example: 1
pageSize:
type: integer
format: int32
example: 20
# Standard error
Error:
type: object
required: [code, message]
properties:
code:
type: string
example: RESOURCE_NOT_FOUND
message:
type: string
example: The requested resource was not found.
details:
type: object
additionalProperties: true
# Timestamps mixin (use allOf)
Timestamps:
type: object
properties:
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
Read reference/security-schemes.md for detailed patterns. Quick reference:
| Scheme | OAS 3.x type | Notes |
|---|---|---|
| Bearer JWT | http, scheme bearer | Most common for REST APIs |
| API Key (header) | apiKey, in header | e.g. X-API-Key |
| API Key (query) | apiKey, in query | Avoid — leaks in logs |
| OAuth 2 | oauth2 | Use flows to define grant types |
| Basic Auth | http, scheme basic | Only over HTTPS |
| OpenID Connect | openIdConnect | Provide openIdConnectUrl |
Apply security globally at the root and override per-operation only where it differs (e.g., public endpoints use security: []).
Path parameters — always required: true:
parameters:
- name: userId
in: path
required: true
schema:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
Query parameters — document defaults and enums:
- name: status
in: query
schema:
type: string
enum: [active, inactive, pending]
default: active
Headers — include X-Request-ID, correlation IDs, etc. as common parameters defined under components/parameters.
Always include at minimum:
| Code | When |
|---|---|
200 | Successful GET, PUT, PATCH |
201 | Successful POST that creates a resource |
204 | Successful DELETE (no body) |
400 | Validation / bad request |
401 | Missing or invalid auth |
403 | Authenticated but not authorized |
404 | Resource not found |
409 | Conflict (duplicate, state mismatch) |
422 | Unprocessable entity (semantic errors) |
429 | Rate limited |
500 | Internal server error |
Use $ref to components/responses for 401, 403, 404, 429, 500 to avoid repetition.
Before delivering the spec, verify:
openapi or swagger version field presentoperationId (camelCase, unique)200/201/204 response4xx and 5xx responses defined for all operations$ref targets exist in components/ or definitions/required array for all request/response bodiesexample per schema or response bodycomponents/schemas is referenced)yaml or json..yaml / .json fileWhen the user provides source code, extract:
Express / Koa / Fastify (Node.js)
.get(), .post(), .put(), .patch(), .delete() calls:param → path parameter {param}authenticate → note security requirementreq.body, req.query, req.params usage → infer request schemaFastAPI / Flask (Python)
@app.get(), @router.post(), etc.Query(), Path(), Body() → map to parameter locationSpring Boot (Java)
@GetMapping, @PostMapping, etc.@PathVariable, @RequestParam, @RequestBodyDjango REST Framework
ViewSet and Router → CRUD endpointsSerializer fields → schema propertiesRails
routes.rb resource routes → standard REST endpointsreference/security-schemes.md — Detailed security scheme examples for all auth typesreference/common-patterns.md — Pagination, HATEOAS, problem+json, webhooks, file upload patternsRead these when the user asks about a specific pattern or when generating complex auth/pagination setups.
Once the OpenAPI/Swagger Specification output is delivered, ask the user:
"Would you like me to generate API test cases for this design? (yes/no)"
If the user says yes:
If the user says no: