Example

Copy into Website see
swagger: “2.0” Use definitions/ Specific structure
openapi: 3.0.0 Use components/ Specific structure
You can also have multiple levels of directories , for example ：components/schema/ Specific structure 、components/securitySchema/ Specific structure etc. .

Example 1

swagger: "2.0"
schemes:
  - https
info: 
  description: "kramer's send message"
  version: "v34"
  title: "kramer"
host: "open.feishu.cn"

paths:
  /open-apis/im/v1/messages:
    post:
      tags:
      # tags send_message What do you mean by the following send_message Under the namespace 
        - "send_message"
      # description  Interface description 
      description: " Send a message "
      #  Function equivalent to description, The two display positions are different 
      summary: "send a message"
      #  Input format , Is an array 
      consumes:
        - "application/json"
      #  Output format , Is an array 
      produces:
        - "application/json"
      # operationId Interface operation identification （ Required ）
      operationId: "SendMessages"
      # parameters parameter information 
      parameters:
        # name  Parameter name 
        - name: "Authorization"
          description: "tenant_access_token"
          # required  If required 
          required: true
          # in  Parameter position ;body, header, formData, query, path（body There can only be one ）
          in: "query"
          # type  Parameter type 
          type: "string"
        - name: "receive_id_type"
          description: " Message Receiver id type "
          required: true
          in: "query"
          # enum  Enumerate optional values 
          enum:
            - "open_id"
            - "user_id"
            - "union_id"
            - "email"
            - "chat_id"
          type: "string"
        - name: "request_body"
          description: " Request body "
          required: true
          in: "body"
          # schema  Parameters refer to the schema 
          schema: 
            # $ref  quote 
            $ref: "#/definitions/send_message"
      # responses  Response body 
      responses:
        # 200  Status code 
        200:
          description: "success"
          schema: 
            $ref: "#/definitions/send_message_response"
# definitions shcmea Definition of reference structure 
definitions:
  #  Definition is named send_message Of schema
  send_message:
    # schema Of type type 
    type: "object"
    # schema Member parameters of properties
    properties:
      receive_id:
        type: "string"
        description: " basis receive_id_type Value , Fill in the corresponding message recipient id"
      content:
        type: "string"
        description: " The message content ,json structure , Different msg_type Corresponding to different contents "
      msg_type:
        type: "string"
        description: " Message type "
    # required  Uniformly define which parameters are required 
    required:
      - "receive_id"
      - "content"
      - "msg_type"
  send_message_response:
    type: "object"
    properties:
      code: 
        type: "string"
        description: " Error code , Not  0  It means failure "
      msg:
        type: "string"
        description: " Error description "
      data:
        type: "object"
        properties:
          message_id:
            type: "string"
            description: ""
          root_id:
            type: "string"
            description: ""

Example 2

# Required fields ！Swagger Specification version , Must fill in 2.0, Otherwise YAML Will not be used for Swagger Other components 
swagger: '2.0'
# Required fields ！ describe API Metadata of interface information 
info:
  # Interface title 
  title: swagger documentation 　
  # Description of the interface document 
  description:  Study Swagger
  # Version number 
  version: 1.0.0
#Swagger Test cases will be provided ,host Specify the host name when testing , If not specified, it is the current host , You can specify the port ．
host: 127.0.0.1
# Defined api The prefix of , Must have / start , The host of the test case is :host＋bashPath
basePath: /api
# Specify the protocol of the calling interface , Must be :"http", "https", "ws", "wss"． The default is http.- Represents an array element , namely schemes Accept an array parameter 
schemes:
  - http
  - https
# Corresponding to http Protocol header request Of Accept, The caller can accept the type , The default is */*, The defined type must be http The agreement defines  Mime Types,RestfulAPI Generally defined as application/json
# These two are global settings for all interfaces , In the refined interface, these two attributes can also be used to override the global attributes 
produces:
  - application/json
# Required fields ! Define actionable API
paths:
  /users:
   # Required fields ! Definition HTTP Operation method , Must be http The method of protocol definition 
    get:
      # Interface Overview 
      summary:  Query all user information 
      # Interface description 
      description:  Find out all the information of all users , user name , Alias 
      # label , It is convenient to filter out User Associated interface 
      tags:
        - User
      # Return value description , Automatically if necessary 
      responses:
        # Back to http Status code 
        200:
          description:  All user information or a collection of user information 
          # Describe the return value 
          schema:
            # Return value format , Optional array,integer,string,boolean
            type: array
            # in the light of array, Format of each entry ,type Defined as array． Fill in if necessary items
            items:
              # Reference in definitions Defined Users
              $ref: '#/definitions/User'
        # Execute error handling 
        default:
          description:  Abnormal operation , Execution failure . The return message describes the details of the error 
          schema:
            # Value type 
            type: object
            # Defining attributes 
            properties:
            # Property name 
              message:
                # type 
                type: string
    # For the same url Define two different methods , Represents two interfaces 
    post:
      description:  Register a user 
      # Request parameters 
      parameters:
          # Parameters key
        - name: username
          # Transfer method ,formData Represents the form transfer , also query Express url Splice transmission ,path To act as url Part of 
          #body Express http Head bearing parameters (body There can only be one , Yes body There can be no other )
          in: formData
          # Parameters to describe 
          description:  user name , You can't use registered 
          # Whether the parameter is necessary , Default false
          required: true
          # Parameter type , Options include array,integer,boolean,string. Use array You have to use items
          type: string
        - name: password
          in: formData
          description:  User login password , The encrypted , Encrypted storage 
          required: true
          type: string
        - name: alias
          in: formData
          type: string
          description:  User alias 
          # Unnecessary fields 
          required: false
      responses:
        # Back to http Status code 
        200:
          description:  The execution result is marked by the return value 　 return true Indicates successful execution 
          schema:
             # Value type 
              type: object
              # Defining attributes 
              properties:
              # Property name 
                status:
                  # type 
                  type: boolean
                  # describe 
                  description:  The success of 
        # Execute error handling 
        default:
          description:  Abnormal operation , Execution failure . The return message describes the details of the error 
          schema:
            # Value type 
            type: object
            # Defining attributes 
            properties:
            # Property name 
              message:
                # type 
                type: string
  /users/{
    id}:
    #{id} Express id For request parameters , for example /users/1,/users/2 It's all right API Request , here id That is to say １ and 2
    get:
      summary:  According to the user name id Query all the information of the user 
      description:  Find out all the information of a user , user name , Nicknames, etc 
      tags:
        - User
      parameters:
        # The interface above defines {id}, Then the parameter list must contain the parameter id, And the request type is path
        - name: id
          in: path
          description:  The user name of the user to query , It is the only identification 
          required: true
          type: string
      responses:
        200:
          description:  All user information or a collection of user information 
          schema:
              $ref: '#/definitions/User'
        default:
          description:  Abnormal operation , Execution failure . The return message describes the details of the error 
          schema:
              # Value type 
              type: object
              # Defining attributes 
              properties:
              # Property name 
                message:
                  # type 
                  type: string
    #http Defined delete Method , Delete a resource 
    delete:
      summary:  Delete user 
      description:  Delete a user's information , Deleted users will not be able to log in 
      parameters:
        - name: id
          in: path
          type: string
          required: true
          description:  Unique identifier of the user 
      tags:
        - User
      responses:
        200:
          description:  The execution result is marked by the return value 　 return true Indicates successful execution 
          schema:
             # Value type 
              type: object
              # Defining attributes 
              properties:
              # Property name 
                status:
                  # type 
                  type: boolean
                  # describe 
                  description:  The success of 
        default:
          description:  Abnormal operation , Execution failure . The return message describes the details of the error 
          schema:
              # Value type 
              type: object
              # Defining attributes 
              properties:
              # Property name 
                message:
                  # type 
                  type: string
                  # Describe the error message 
    #http Defined patch Method , Indicates modifying a resource 
    patch:
      summary:  User information modification 
      description:  Modify user information ( Username alias )
      parameters: 
        - name: id
          in: path
          description:  user name , Unique identifier of the data to be modified 
          required: true
          type: string
        - name: alias
          in: formData
          description:  New user alias 
          required: true
          type: string
      tags:
        - User
      responses:
        200:
          description:  The execution result is marked by the return value 　 return true Indicates successful execution 
          schema:
            # Value type 
              type: object
              # Defining attributes 
              properties:
              # Property name 
                status:
                  # type 
                  type: boolean
                  # describe 
                  description:  The success of 
        default:
          description:  Abnormal operation , Execution failure . The return message describes the details of the error 
          schema:
              # Value type 
              type: object
              # Defining attributes 
              properties:
              # Property name 
                message:
                  # type 
                  type: string
                  # Describe the error message 
definitions:
  User:
    # Value type 
    type: object
    # Defining attributes 
    properties:
    # Property name 
      id:
        # type 
        type: string
        # describe 
        description:  User's uniqueness id
      username:
        type: string
        description:  user name 
      alias:
        type: string
        description:  Alias 

Example 3 openapi 3.0.0

openapi: 3.0.0
info:
  version: 1.2.0
  title: ka config request
  description:  Enterprise training allocation API
servers:
  - url: 'http://localhost:18080/api/v1/config'

components:
  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    errorResponse:
      type: object
      properties:
        code:
          type: string
          description:  Status code 
        message:
          type: string
          description:  Description information 
    Error:
      type: object
      properties:
        timestamp:
          type: string
        status:
          type: integer
          format: int32
        error:
          type: string
        path:
          type: string
    defaultConfig:
      type: object
      required:
        - welcome_message
        - calendar_permissions
        - b_show_on_main_calendar
        - event_reminder_minutes
        - task_complete_statistics
      properties:
        sync_method:
          type: string
          description:  Synchronization method ,  Optional fields , enum(lark_cloud_table,interface, third_party_product),  Can pass enumeration index (int) Or worth it (string)
        sync_frequency:
          type: string
          description:  Synchronization frequency ,  Optional fields , enum(real_time, cron),  Can pass enumeration index (int) Or worth it (string)
        welcome_message:
          type: string
          description:  Welcome to the group ,  The longest 2047 character 
        calendar_permissions:
          type: string
          description:  Calendar disclosure scope , enum(private, public, show_only_free_busy),  Can pass enumeration index (int) Or worth it (string)
        b_show_on_main_calendar:
          type: boolean
          description:  Whether to display to the user's main calendar 
        event_reminder_minutes:
          description: ( From the flying book open platform document )  Offset of schedule reminder time , A positive number indicates that before the start of the schedule X Minute reminder , Negative numbers indicate that after the start of the schedule X Minute reminder   Value range ：-20160 ～ 20160
          type: array
          items:
            type: integer
            format: int32
        task_complete_statistics:
          type: string
          description:  Intra group task reminder , enum(enable, disable, only_teacher_and_organizer),  Can pass enumeration index (int) Or worth it (string)
        task_reminder_minutes:
          description: ( From the flying book open platform document )  Reminder time relative to the deadline （ If in advance  30  minute , After the deadline  30  minute , Then for  -30）
          type: array
          items:
            type: integer
            format: int32
        can_join_course_via_calendar:
          type: boolean
          description:  Whether you can join the course through the schedule 
        auto_create_chat:
          type: boolean
          description:  Whether to automatically create course group chat 
        advance_days:
          type: integer
          format: int32
          description:  Lead time for automatically creating group chat （ Company ： God ）
        welcome_type:
          type: string
          description:  Welcome format 
        title:
          type: string
          description:  Welcome title 
        text:
          type: string
          description:  Welcome text 
        button_text:
          type: string
          description:  Button text 
        button_url:
          type: string
          description:  Button link 
        img_key:
          type: string
          description:  picture 
        task_id:
          type: integer
          format: int64
          description:  Mission id
        chat_reminder_days:
          type: string
          description:  Group chat 
        reminder_content:
          type: string
          description:  Keep the text 
    course:
      type: object
      required:
        - course_id
        - name
        - description
        - calendar_permissions
        - b_show_on_main_calendar
        - manager
      properties:
        course_id:
          type: string
          description:  Course  id
        name:
          type: string
          description:  Course name 
        description:
          type: string
          description:  Course description 
        calendar_permissions:
          type: string
          description:  Calendar disclosure scope , enum(private, public, show_only_free_busy),  Can pass enumeration index (int) Or worth it (string)
        b_show_on_main_calendar:
          type: boolean
          description:  Whether to display to the user's main calendar 
        manager:
          type: array
          description:  List of course Administrators 
          items:
            type: object
            properties:
              name:
                type: string
    courseConfig:
      type: object
      required:
        - welcome_message
        - calendar_permissions
        - b_show_on_main_calendar
      properties:
        welcome_message:
          type: string
          description:  Welcome to the group ,  The longest 2047 character 
        calendar_permissions:
          type: string
          description:  Calendar disclosure scope , enum(private, public, show_only_free_busy),  Can pass enumeration index (int) Or worth it (string)
        b_show_on_main_calendar:
          type: boolean
          description:  Whether to display to the user's main calendar 
        event_reminder_minutes:
          description: ( From the flying book open platform document )  Offset of schedule reminder time , A positive number indicates that before the start of the schedule X Minute reminder , Negative numbers indicate that after the start of the schedule X Minute reminder   Value range ：-20160 ～ 20160
          type: array
          items:
            type: integer
            format: int32
        can_join_course_via_calendar:
          type: boolean
          description:  Whether you can join the course through the schedule 
        auto_create_chat:
          type: boolean
          description:  Whether to automatically create group chat 
        advance_days:
          type: integer
          format: int32
          description:  Automatically create group chat lead time （ Company ： God ）
        need_survey:
          type: boolean
          description:  Do you need a questionnaire 
        survey_url:
          type: string
          description:  Questionnaire link 
        welcome_type:
          type: string
          description:  Welcome type 
        title:
          type: string
          description:  Welcome title 
        text:
          type: string
          description:  Welcome text 
        button_text:
          type: string
          description:  Button text 
        button_url:
          type: string
          description:  Button link 
        img_key:
          type: string
          description:  picture 
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/task'

    courseUpdateConfig:
      type: object
      required:
        - calendar_permissions
        - b_show_on_main_calendar
      properties:
        calendar_permissions:
          type: string
          description:  Calendar disclosure scope , enum(private, public, show_only_free_busy),  Can pass enumeration index (int) Or worth it (string)
        b_show_on_main_calendar:
          type: boolean
          description:  Whether to display to the user's main calendar 
        event_reminder_minutes:
          description: ( From the flying book open platform document )  Offset of schedule reminder time , A positive number indicates that before the start of the schedule X Minute reminder , Negative numbers indicate that after the start of the schedule X Minute reminder   Value range ：-20160 ～ 20160
          type: array
          items:
            type: integer
            format: int32
        tasks:
          description:  Task list 
          type: array
          items:
            type: object
            required:
              - task_id
              - task_complete_statistics
            properties:
              task_id:
                type: integer
                format: int64
                description:  Mission id
              task_complete_statistics:
                type: string
                description:  Intra group task reminder , enum(enable, disable, only_teacher_and_organizer),  Can pass enumeration index (int) Or worth it (string)
              task_reminder_minutes:
                description: ( From the flying book open platform document )  Reminder time relative to the deadline （ If in advance  30  minute , After the deadline  30  minute , Then for  -30）
                type: array
                items:
                  type: integer
                  format: int32
    task:
      type: object
      required:
        - task_id
        - name
        - description
        - task_complete_statistics
      properties:
        task_id:
          type: string
          description:  Mission  id
        name:
          type: string
          description:  The name of the task 
        description:
          type: string
          description:  Task description 
        task_complete_statistics:
          type: string
          description:  Intra group task reminder , enum(enable, disable, only_teacher_and_organizer),  Can pass enumeration index (int) Or worth it (string)
        task_reminder_minutes:
          description: ( From the flying book open platform document )  Reminder time relative to the deadline （ If in advance  30  minute , After the deadline  30  minute , Then for  -30）
          type: array
          items:
            type: integer
            format: int32
    taskConfig:
      type: object
      required:
        - task_complete_statistics
      properties:
        task_complete_statistics:
          type: string
          description:  Intra group task reminder , enum(enable, disable, only_teacher_and_organizer),  Can pass enumeration index (int) Or worth it (string)
        task_reminder_minutes:
          description: ( From the flying book open platform document )  Reminder time relative to the deadline （ If in advance  30  minute , After the deadline  30  minute , Then for  -30）
          type: array
          items:
            type: integer
            format: int32
    pageInfo:
      type: object
      required:
        - page_size
        - page_num
        - total_cnt
      properties:
        page_size:
          type: integer
          format: int32
          description:  Page size 
        page_num:
          description:  Page number （ from 0 Start )
          type: integer
          format: int32
        total_cnt:
          description:  The total number of data 
          type: integer
          format: int32
    courseListConfig:
      type: object
      required:
        - welcome_message
        - calendar_permissions
        - b_show_on_main_calendar
        - event_reminder_minutes
        - task_complete_statistics
      properties:
        welcome_message:
          type: string
          description:  Welcome to the group ,  The longest 2047 character 
        calendar_permissions:
          type: string
          description:  Calendar disclosure scope , enum(private, public, show_only_free_busy),  Can pass enumeration index (int) Or worth it (string)
        b_show_on_main_calendar:
          type: boolean
          description:  Whether to display to the user's main calendar 
        event_reminder_minutes:
          description: ( From the flying book open platform document )  Offset of schedule reminder time , A positive number indicates that before the start of the schedule X Minute reminder , Negative numbers indicate that after the start of the schedule X Minute reminder   Value range ：-20160 ～ 20160
          type: array
          items:
            type: integer
            format: int32
        task_complete_statistics:
          type: string
          description:  Intra group task reminder , enum(enable, disable, only_teacher_and_organizer),  Can pass enumeration index (int) Or worth it (string)
        task_reminder_minutes:
          description: ( From the flying book open platform document )  Reminder time relative to the deadline （ If in advance  30  minute , After the deadline  30  minute , Then for  -30）
          type: array
          items:
            type: integer
            format: int32



paths:
  /courseconfig:
    put:
      summary: ' Batch modify course configuration '
      security:
        - tokenAuth: [ ]
      tags:
        - course
      requestBody:
        content:
          application/json:
            schema:
              properties:
                course_config:
                  $ref: '#/components/schemas/courseListConfig'
                course_id_list:
                  type: array
                  items:
                    type: integer
                    format: int64
      responses:
        '200':
          description: 'update success'
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description:  Status code 
                  message:
                    type: string
                    description:  Description information 
                  data:
                    $ref: '#/components/schemas/courseListConfig'
        'x-40410':
          description: 'course not found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /globalcalendar:
    put:
      summary:  Turn on / Close global calendar 
      tags:
        - default
      security:
        - tokenAuth: [ ]
      requestBody:
        content:
          application/json:
            schema:
              properties:
                open_global_calendar:
                  type: boolean
      responses:
        '200':
          description: 'update success'
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description:  Status code 
                  message:
                    type: string
                    description:  Description information 
                  data:
                    properties:
                      open_global_calendar:
                        type: boolean
        '400':
          description: 'Bad Request'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /defaultconfig:
    post:
      summary:  Update the enterprise default configuration 
      tags:
        - default
      security:
        - tokenAuth: [ ]
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/defaultConfig'
      responses:
        '200':
          description: 'Created'
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description:  Status code 
                  message:
                    type: string
                    description:  Description information 
                  data:
                    $ref: '#/components/schemas/defaultConfig'
        'x-50011':
          description: unexpected response of lark request 'create calendar'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      summary:  Get the enterprise default configuration 
      tags:
        - default
      security:
        - tokenAuth: [ ]
      responses:
        '200':
          description: 'require success'
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description:  Status code 
                  message:
                    type: string
                    description:  Description information 
                  data:
                    $ref: '#/components/schemas/defaultConfig'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /courseconfig/{
    course_id}:
    get:
      summary: ' Get a course configuration '
      security:
        - tokenAuth: [ ]
      tags:
        - course
      parameters:
        - name: course_id
          in: path
          required: true
          description:  Course  id
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/courseConfig'
      responses:
        '200':
          description: 'require success'
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description:  Status code 
                  message:
                    type: string
                    description:  Description information 
                  data:
                    $ref: '#/components/schemas/courseConfig'
        'x-40410':
          description: 'course not found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: ' Modify a course configuration '
      security:
        - tokenAuth: [ ]
      tags:
        - course
      parameters:
        - name: course_id
          in: path
          required: true
          description:  Course  id
          schema:
            type: integer
            format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/courseUpdateConfig'
      responses:
        '200':
          description: 'update success'
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description:  Status code 
                  message:
                    type: string
                    description:  Description information 
                  data:
                    $ref: '#/components/schemas/courseUpdateConfig'
        'x-40410':
          description: 'course not found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        'x-40411':
          description: 'task not found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'