【萌狼蓝天】swagger速成

相关链接

编辑器：https://editor.swagger.io/
文档：https://openapi.apifox.cn/

基础信息设置

openapi: 3.0.3
info:
  title: 后端服务接口
  description: |-
    ## 描述
    由萌狼蓝天创建
    
    
    ## 相关介绍
    `terOfServer`：服务隐私条款
    
    ## 相关连接
    
    
    
  termsOfService: https://mllt.cc
  contact:
    email: mllt9920@qq.com
  license:
    name: Apache 2.0
    url: https://mllt.cc
  version: 1.0.0
externalDocs:
  description: 萌狼蓝天的博客园
  url: https://cnblogs.com/mllt
  
servers:
  - url: https://api.mllt.cc/api/v2024

image

一个简单的例子

openapi: 3.0.3
info:
  title: 后端服务接口
  description: |-
    ## 描述
    由萌狼蓝天创建
    
    
    ## 相关介绍
    `terOfServer`：服务隐私条款
    
    ## 相关连接
    
    
    
  termsOfService: https://mllt.cc
  contact:
    email: mllt9920@qq.com
  license:
    name: Apache 2.0
    url: https://mllt.cc
  version: 1.0.0
externalDocs:
  description: 萌狼蓝天的博客园
  url: https://cnblogs.com/mllt
  
servers:
  - url: https://api.mllt.cc/api/v2024
  
  
tags:
  - name: user
    description: 用户相关接口
    externalDocs:
      description: 接口地址
      url: https://api.mllt.cc/api/user

paths:
  /user/get:
    get:
      tags:
        - 用户列表
      summary: 所有用户
      description: 获取所有的用户信息
      responses:
        '200':
          description: 成功获取所有的用户
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
            description: 获取失败，请检查前端
        '500':
            description: 获取失败，请检查后端
        '404':
            description: 获取失败，请检查后端是否正常运行，是否存在跨域问题  
  /user/add:
    post:
      tags:
        - 用户新增
      summary: 新增用户
      description: 新增一个用户
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: 成功新增用户
          content:
           application/json:
            schema:
              $ref: '#/components/schemas/User'
        '400':
          description: 失败，请检查前端
        '500':
          description: 失败，请检查后端
        '404':
          description: 失败，请检查后端是否正常运行，是否存在跨域问题           
  
  
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        username:
          type: string
          example: 萌狼蓝天
        firstName:
          type: string
          example: 萌狼
        lastName:
          type: string
          example: 蓝天
        email:
          type: string
          example: mllt9920@qq.com
        password:
          type: string
          example: '123456'
        phone:
          type: string
          example: '13140209920'
        userStatus:
          type: integer
          description: User Status
          format: int32
          example: 1
      xml:
        name: user
  requestBodies:
    User:
      description: User对象
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/User'
        application/xml:
          schema:
            $ref: '#/components/schemas/User'
    UserArray:
      description: List of user object
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/User'

借助工具

我个人爱用apifox

apifox支持导出openapi(swagger)-json格式的文件

可以用在线工具转为yaml格式（例如：https://json2yaml.com/）
但是转换后可能会因为有一些地方有问题
比如说没设置字段type的，为null的时候，就会出问题

如果想用工具来写的话，我个人认为应该尽可能的去完整、规范的填写

看一看转后的效果

openapi: 3.0.0
info:
  title: server-system
  description: ''
  version: 1.0.0
tags:
- name: 用户相关
- name: 资讯相关
paths:
  "/users":
    get:
      summary: 用户_查询_全部
      x-apifox-folder: 用户相关
      x-apifox-status: developing
      deprecated: false
      description: 查询全部用户
      tags:
      - 用户相关
      parameters: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    userId:
                      type: integer
                    userNickname:
                      type: string
                    userAccount:
                      type: string
                    userPassword:
                      type: string
                    userRegTime:
                      type: string
                    userLastLoginTime:
                      type: string
                    userStatus:
                      type: integer
                    userIdentity:
                      type: string
                    remarks:
                      type: string
                  required:
                  - userId
                  - userNickname
                  - userAccount
                  - userPassword
                  - userRegTime
                  - userLastLoginTime
                  - userStatus
                  - userIdentity
                  - remarks
                  x-apifox-orders:
                  - userId
                  - userNickname
                  - userAccount
                  - userPassword
                  - userRegTime
                  - userLastLoginTime
                  - userStatus
                  - userIdentity
                  - remarks
                  x-apifox-ignore-properties: []
      x-run-in-apifox: https://apifox.com/web/project/3965777/apis/api-144831280-run
      security: []
    post:
      summary: 用户_新增
      x-apifox-folder: 用户相关
      x-apifox-status: developing
      deprecated: false
      description: ''
      tags:
      - 用户相关
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userNickname:
                  type: string
                  description: 用户昵称
                userAccount:
                  type: string
                  description: 用户账号
                userPassword:
                  type: string
                  description: 用户密码
                userIdentity:
                  type: string
                  description: 用户身份
                remarks:
                  type: string
                  description: 备注
              required:
              - userNickname
              - userAccount
              - userPassword
              - remarks
              - userIdentity
              x-apifox-orders:
              - userNickname
              - userAccount
              - userPassword
              - userIdentity
              - remarks
              x-apifox-ignore-properties: []
            example:
              userNickname: JohnDoe
              userAccount: johndoe123
              userPassword: password123
              userIdentity: 测试员
              remarks: 测试用户
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apifox-ignore-properties: []
                x-apifox-orders: []
      x-run-in-apifox: https://apifox.com/web/project/3965777/apis/api-144847680-run
      security: []
    put:
      summary: 用户_更新
      x-apifox-folder: 用户相关
      x-apifox-status: developing
      deprecated: false
      description: ''
      tags:
      - 用户相关
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userNickname:
                  type: string
                  description: 用户昵称
                userPassword:
                  type: string
                  description: 用户密码
                userIdentity:
                  type: string
                  description: 用户身份
                remarks:
                  type: string
                  description: 备注
                userStatus:
                  type: string
                  description: 用户状态
                userId:
                  type: string
                  description: 用户ID
                userLoginTime:
                  type: string
              required:
              - userId
              x-apifox-orders:
              - userNickname
              - userPassword
              - userIdentity
              - remarks
              - userStatus
              - userId
              - userLoginTime
              x-apifox-ignore-properties: []
            example:
              userNickname: JohnDoe
              userAccount: johndoe123
              userPassword: password123
              userIdentity: 测试员
              remarks: 测试用户
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apifox-ignore-properties: []
                x-apifox-orders: []
      x-run-in-apifox: https://apifox.com/web/project/3965777/apis/api-144895492-run
      security: []
  "/users/6":
    get:
      summary: 用户_查询_根据ID
      x-apifox-folder: 用户相关
      x-apifox-status: developing
      deprecated: false
      description: ''
      tags:
      - 用户相关
      parameters: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apifox-ignore-properties: []
                x-apifox-orders: []
      x-run-in-apifox: https://apifox.com/web/project/3965777/apis/api-144872718-run
      security: []
  "/users/4":
    delete:
      summary: 用户_删除_根据ID
      x-apifox-folder: 用户相关
      x-apifox-status: developing
      deprecated: false
      description: ''
      tags:
      - 用户相关
      parameters: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apifox-ignore-properties: []
                x-apifox-orders: []
      x-run-in-apifox: https://apifox.com/web/project/3965777/apis/api-144891769-run
      security: []
  "/users/login":
    post:
      summary: 用户_登录
      x-apifox-folder: 用户相关
      x-apifox-status: developing
      deprecated: false
      description: ''
      tags:
      - 用户相关
      parameters:
      - name: userAccount
        in: query
        description: ''
        required: false
        example: wenjun
        schema:
          type: string
      - name: userPassword
        in: query
        description: ''
        required: false
        example: '123456'
        schema:
          type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apifox-ignore-properties: []
                x-apifox-orders: []
      x-run-in-apifox: https://apifox.com/web/project/3965777/apis/api-144929527-run
      security: []
  "/informationTable/all":
    get:
      summary: 资讯_查询_全部
      x-apifox-folder: 资讯相关
      x-apifox-status: developing
      deprecated: false
      description: ''
      tags:
      - 资讯相关
      parameters: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apifox-ignore-properties: []
                x-apifox-orders: []
      x-run-in-apifox: https://apifox.com/web/project/3965777/apis/api-145428475-run
      security: []
  "/informationTable/add":
    post:
      summary: 资讯_新增
      x-apifox-folder: 资讯相关
      x-apifox-status: developing
      deprecated: false
      description: ''
      tags:
      - 资讯相关
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                content:
                  type: string
                type:
                  type: string
                attachments:
                  type: string
                creator:
                  type: string
              x-apifox-orders:
              - title
              - content
              - type
              - attachments
              - creator
              required:
              - title
              - content
              - creator
              - attachments
              - type
              x-apifox-ignore-properties: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apifox-ignore-properties: []
                x-apifox-orders: []
      x-run-in-apifox: https://apifox.com/web/project/3965777/apis/api-145430645-run
      security: []
  "/informationTable/get/1":
    get:
      summary: 资讯_查询_根据ID
      x-apifox-folder: 资讯相关
      x-apifox-status: developing
      deprecated: false
      description: ''
      tags:
      - 资讯相关
      parameters: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apifox-ignore-properties: []
                x-apifox-orders: []
      x-run-in-apifox: https://apifox.com/web/project/3965777/apis/api-145430948-run
      security: []
  "/informationTable/update":
    put:
      summary: 资讯_更新_根据ID
      x-apifox-folder: 资讯相关
      x-apifox-status: developing
      deprecated: false
      description: ''
      tags:
      - 资讯相关
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                content:
                  type: string
                type:
                  type: string
                attachments:
                  type: string
                creator:
                  type: string
                id:
                  type: string
              x-apifox-orders:
              - title
              - content
              - type
              - attachments
              - creator
              - id
              required:
              - title
              - content
              - creator
              - attachments
              - type
              - id
              x-apifox-ignore-properties: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apifox-ignore-properties: []
                x-apifox-orders: []
      x-run-in-apifox: https://apifox.com/web/project/3965777/apis/api-145430958-run
      security: []
  "/informationTable/delete/2":
    delete:
      summary: 资讯_删除
      x-apifox-folder: 资讯相关
      x-apifox-status: developing
      deprecated: false
      description: 删除成功code1，当data为1时是有数据成功删除，当data为0时表示数据库根本没这条数据
      tags:
      - 资讯相关
      parameters: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apifox-ignore-properties: []
                x-apifox-orders: []
      x-run-in-apifox: https://apifox.com/web/project/3965777/apis/api-145431877-run
      security: []
  "/informationTable/statistics":
    get:
      summary: 资讯_数据统计
      x-apifox-folder: 资讯相关
      x-apifox-status: developing
      deprecated: false
      description: ''
      tags:
      - 资讯相关
      parameters: []
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties: {}
                x-apifox-ignore-properties: []
                x-apifox-orders: []
      x-run-in-apifox: https://apifox.com/web/project/3965777/apis/api-145432712-run
      security: []
components:
  schemas: {}
  securitySchemes: {}
servers:
- url: http://test-cn.your-api-server.com
  description: 测试环境
- url: http://localhost:8080
  description: 开发环境
- url: http://prod-cn.your-api-server.com
  description: 正式环境

image

image

个人认为还是可以的。（只是里面似乎夹带了一点apifox的私货啊，算了影响不大）

posted @ 2024-03-12 12:36  萌狼蓝天  阅读(10)  评论(0)  编辑  收藏  举报