当你需要根据自然语言描述、代码或部分规范生成完整的、可投入生产的 OpenAPI 3.x 和 Swagger 2.0 规范时，请使用此技能。每当用户提到 OpenAPI、Swagger、API 规范、REST API 文档、YAML/JSON API 架构、端点文档、API 时，请使用此技能...

从描述、代码或部分规范生成完整、有效的 OpenAPI 3.x 或 Swagger 2.0 规范。

在编写任何 YAML/JSON 之前，先询问（或根据上下文推断）以下内容：

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

如果用户提供代码（Express 路由、FastAPI、Django URL、Spring 控制器等），自动提取端点 —— 不要询问用户已经告诉你的内容。

遵循所选版本的结构指南。始终生成完整、有效的规范——绝不要留下类似 # TODO: add schema 的占位符注释。

openapi: "3.1.0"
info:
  title: <API Title>
  version: "1.0.0"
  description: <Short description>
  contact:
    name: <Team or Author>
    email: <contact@example.com>
servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging
tags:
  - name: <Tag>
    description: <Tag description>
paths:
  /resource:
    get:
      summary: List resources
      operationId: listResources
      tags: [<Tag>]
      parameters: []
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceList"
              example:
                items: []
                total: 0
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
      security:
        - BearerAuth: []
components:
  schemas: {}
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  securitySchemes: {}

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: {}

# 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

查看 reference/security-schemes.md 以获取详细模式。快速参考：

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

在根目录全局应用安全性，并仅在操作有所不同的情况下覆盖（例如，公共端点使用 security: []）。

路径参数 — 始终 required: true：

parameters:
  - name: userId
    in: path
    required: true
    schema:
      type: string
      format: uuid
    example: 123e4567-e89b-12d3-a456-426614174000

查询参数 — 文档默认值和枚举：

  - name: status
    in: query
    schema:
      type: string
      enum: [active, inactive, pending]
      default: active

请求头 — 包括 X-Request-ID、关联 ID 等，作为在 components/parameters 下定义的通用参数。

201 Successful POST that creates a resource

422 Unprocessable entity (semantic errors)

使用 $ref 指向 components/responses 来处理 401、403、404、429、500，以避免重复。

当用户询问特定模式或在生成复杂的认证/分页设置时，请阅读这些内容。

一旦 OpenAPI/Swagger 规范输出被交付，询问用户：

您希望我为这个设计生成 API 测试用例吗？（是/否）

来源说明：本文内容整理自开源项目 agentic-awesome-skills（中文翻译版），遵循 CC BY 4.0（知识共享署名 4.0 国际）许可协议，此处作为中文资料整理分享，版权归原作者所有。

Openapi Spec Generator 实用指南

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...

开发工具

后端

架构设计

本文提供OpenAPI Spec Generator实用指南，涵盖从自然语言或代码生成生产级OpenAPI 3.x与Swagger 2.0规范的完整工作流。详解上下文收集、规范骨架、数据模型、安全方案、参数及响应定义，并附质量检查表与代码提取示例，助您快速构建有效API文档。

身份验证

Spring Boot

服务器

中间件

Python

路由

Django

OAuth

Agent

Java

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

Openapi Spec Generator 实用指南

Openapi Spec Generator 实用指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐