OpenAPI template generator

Generate an OpenAPI 3.1 skeleton: info, servers, tags, CRUD paths per resource, components.schemas, securitySchemes and common response codes, printed as YAML you can commit.

Runs in your browserEvery computation happens in your browser — your data never leaves this device.

Document info

API titleVersion (e.g. 1.0.0)servers (one URL per line)Description (optional)

Authentication

Add 400 / 401 / 500 common responses

Resources

Available operations: list, create, get, update, delete

One resource per line: name:operations:idField:idType:paginatefor example pets:list,create,get,update,delete:id:integer:yes

openapi.yaml

Save the output as openapi.yaml; Swagger UI, Redoc and openapi-generator all read it.

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: []

Statistics

Paths2

Operations5

Schemas4

Tags1

Lines0

What this tool does

Agree on the contract first: fill in the title, servers and resource names, generate every CRUD path and schema in one go, and review the YAML as a team.
Feed mocks or SDKs: point Swagger UI at the YAML for docs and openapi-generator at it for client code, both from the same definition.
Standardise a team: authentication, pagination parameters and the error shape come from the template instead of being reinvented per endpoint.
When writing docs costs more than the code: enter the model names and id rules, and paths, operationIds and $refs are generated for you.

Example

Input

Title: Pet Store API
Version: 1.0.0
servers: https://api.example.com/v1
Auth: none
Resources: pets:list:id:integer:no
Common responses: off

Output

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

Status codes are quoted string keys ('200') because OpenAPI requires it, and the model name is derived from the resource name: pets becomes Pet.

Frequently asked questions

Can the YAML be used as is?

Yes. It conforms to OpenAPI 3.1 and can be fed to Swagger UI, Redoc or openapi-generator. Every schema is referenced with $ref into components.schemas, so there are no dangling references.

How should resources be named?

Use the lowercase plural path segment, for example pets or order-items. Model names are derived automatically: order-items becomes OrderItem and categories becomes Category; set an explicit model name when the guess is wrong.

When do pagination parameters appear?

Only when the list operation exists and pagination is on: page and pageSize query parameters are added and the response points at the <Model>List wrapper. With pagination off, list references the model directly and no List schema is emitted.

What does the authentication option generate?

bearer produces an http + bearer + JWT security scheme, basic an http + basic scheme, and API key a header-based X-API-Key scheme, each referenced from the top-level security field. Choosing none omits both securitySchemes and the 401 response.

Can operationIds collide?

No. Collection operations use the plural resource name (listPets) while single-item operations use the singular model (getPet, replacePet, deletePet). Duplicate resource names are rejected during validation.

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

What this tool does

Example

Frequently asked questions

Related tools