跳到主内容
UniKit

OpenAPI 模板

生成 OpenAPI 3.1 骨架：info、servers、tags、按资源展开的 CRUD 路径、components.schemas、securitySchemes 与常见响应码，输出可直接放进仓库的 YAML。

浏览器本地运行所有计算都在你的浏览器里完成，数据不会离开本机。

文档信息

鉴权方式
补上 400 / 401 / 500 通用响应

资源

可用操作：list, create, get, update, delete

openapi.yaml

把内容保存成 openapi.yaml，可直接被 Swagger UI、Redoc 或 openapi-generator 读取。

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
  description: 由 UniKit 生成的 OpenAPI 骨架，按需增删字段即可。
servers:
  - url: https://api.example.com/v1
tags:
  - name: pets
    description: Pet resources
paths:
  /pets:
    get:
      tags:
        - pets
      summary: List pets
      operationId: listPets
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          description: Items per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: sort
          in: query
          description: Sort expression, e.g. -createdAt
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PetList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
        - pets
      summary: Create a pet
      operationId: createPet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetInput'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pets/{id}:
    get:
      tags:
        - pets
      summary: Get a pet
      operationId: getPet
      parameters:
        - name: id
          in: path
          required: true
          description: Pet identifier
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
        - pets
      summary: Replace a pet
      operationId: replacePet
      parameters:
        - name: id
          in: path
          required: true
          description: Pet identifier
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetInput'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - pets
      summary: Delete a pet
      operationId: deletePet
      parameters:
        - name: id
          in: path
          required: true
          description: Pet identifier
          schema:
            type: integer
      responses:
        '204':
          description: Deleted
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
        message:
          type: string
        details:
          type: array
          items:
            type: string
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
        name:
          type: string
          description: Display name
        description:
          type:
            - string
            - 'null'
          description: Optional long text
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    PetInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Display name
        description:
          type:
            - string
            - 'null'
          description: Optional long text
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    PetList:
      type: object
      required:
        - items
        - total
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Pet'
        total:
          type: integer
          description: Total number of records
        page:
          type: integer
          minimum: 1
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []

统计

路径数2
操作数5
Schema 数4
标签数1
行数0

这个工具能做什么

  • 新项目立项先把接口骨架定下来：填好标题、servers 和资源名，一次生成所有 CRUD 路径与 schema，团队先对着这份 YAML 讨论字段。
  • 给前端造 mock 或 SDK：把 YAML 丢给 Swagger UI 看文档、给 openapi-generator 生成客户端代码，两边共用同一份定义。
  • 统一团队规范：鉴权方式、分页参数、错误响应结构都由模板给出，避免每个接口各写一套。
  • 补文档比写代码还累时：已有模型名和主键规则填进资源行，剩下的路径、operationId、$ref 全部自动生成。

示例

输入

标题：Pet Store API
版本：1.0.0
servers：https://api.example.com/v1
鉴权：无
资源：pets:list:id:integer:no
通用响应：关闭

输出

openapi: 3.1.0
info:
  title: Pet Store API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
tags:
  - name: pets
    description: Pet resources
paths:
  /pets:
    get:
      tags:
        - pets
      summary: List pets
      operationId: listPets
      parameters:
        - name: sort
          in: query
          description: Sort expression, e.g. -createdAt
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
        message:
          type: string
        details:
          type: array
          items:
            type: string
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
        name:
          type: string
          description: Display name
        description:
          type:
            - string
            - 'null'
          description: Optional long text
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    PetInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Display name
        description:
          type:
            - string
            - 'null'
          description: Optional long text
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true

状态码会被写成字符串键（'200'），这是 OpenAPI 的要求；模型名由资源名推导，pets 得到 Pet。

常见问题

生成的 YAML 能直接跑起来吗？

能。文档符合 OpenAPI 3.1，可以直接喂给 Swagger UI、Redoc 或 openapi-generator；路径里的 schema 用 $ref 指向 components.schemas，不会出现悬空引用。

资源名该怎么填？

用小写复数的路径片段，例如 pets、order-items。模型名会自动推导：order-items → OrderItem，categories → Category；如果推导不符合预期，可以在资源行里显式给出模型名。

分页参数是什么时候出现的？

只有 list 操作且开启分页时才会加 page / pageSize 查询参数，并把响应指向 <模型>List 包装对象；关掉分页后 list 直接返回模型数组的引用，文档里也不会出现 List schema。

鉴权部分生成什么？

bearer 生成 http + bearer + JWT 的 securityScheme，basic 生成 http + basic，API Key 生成 header 形式的 X-API-Key，并在顶层加 security 引用。选择「无」时既不写 securitySchemes 也不写 401 响应。

operationId 会冲突吗？

不会。list 用资源复数名（listPets），单个资源的操作统一用模型名单数（getPet、replacePet、deletePet）。同一资源只生成一份，重复资源名会在校验阶段直接报错。

关键词：openapiswaggerapi specrest apiopenapi 模板接口文档api 规范crud 接口swagger yaml接口骨架

同类工具

API 响应格式数据与序列化Bencode 解码数据与序列化CBOR 查看数据与序列化图表生成器数据与序列化信用卡验证数据与序列化CSV / JSON 互转数据与序列化