Swagger Editor编写

最新推荐文章于 2024-08-08 08:31:05 发布
最新推荐文章于 2024-08-08 08:31:05 发布
阅读量1.6k 收藏 3
点赞数
分类专栏： 技术学习 文章标签： swagger2
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/tktttt/article/details/118108966
版权

Swagger Editor编写

一、Swagger Editor编辑器

1.在线编写

https://editor.swagger.io/
其是官方提供的编写swagger yaml文件的在线编辑器，且可以实时看见编写的yaml文件的可视化页面

2.IDEA安装插件

在插件库中搜索swagger，会出现一堆swagger editor相关的插件，本文选择的是 OpenAPI（Swagger）Editor。
安装插件并重启idea后，新建yaml文件即可进行编写，如下图：

3.两种方式优缺点

在线：无提示与智能补全，有可视化页面，编写的同时会及时展示可视化界面。另外，其有比较好的报错提示。
idea：有提示与智能补全，有可视化页面，但可视化界面反应较慢。其错误提示较差。

建议两种方式搭配使用：idea编写、在线查看。

二、语法规则

1.字段类型与格式定义

在这里插入图片描述

Swagger API包含以下部分：

参数包含的参数部分含义
swagger–必需，指定swagger spec版本，2.0
info–必需，提供API的元数据
tags–建议必需，补充的元数据，在swagger ui中，用于作为api的分组标签
host–必需，主机、域名，如果没有提供，则使用文档所在的host
basePath–相对于host的路径
schemes–必需，API的传输协议，http，https，ws，wss
consumes–API可以消费的MIME类型列表
produces–API产生的MIME类型列表
pathsAPI的路径，以及每个路径的HTTP方法，一个路径加上一个HTTP方法构成了一个操作。每个操作都有以下内容:
tags操作的标签
summary短摘要
description描述
externalDocs外部文档
operationId标识操作的唯一字符串
consumesMIME类型列表
producesMIME类型列表
parameters参数列表
responses应答状态码等
schemes传输协议
deprecated是否弃用，默认false，不推荐使用
security安全
definitions定义API消费或生产的数据类型，使用json-schema描述，操作的parameter和response部分可以通过引用的方式使用definitions部分定义的schema
parameters多个操作共用的参数
responses多个操作共用的响应
securityDefinitions–安全scheme定义
security–安全声明
externalDocs–附加的外部文档

详细可见官网：
https://swagger.io/docs/specification/2-0/basic-structure/

另外注意排版，其语法要求严格对齐。

三、示例说明

1.编写get-yaml示例

文件取名自定义，建议有标识度，以.yaml结尾，如：DeviceQuery.yaml

##必要字段！Swagger规范版本，必须填2.0，否则该YAML将不能用于Swagger其他组件
swagger: "2.0"
#必要字段！描述API接口信息的元数据
info:
  #接口标题
  title: 设备管理服务
  #接口文档的描述
  description: 包含设备管理接口
  #版本号，自定义
  version: 1.0.0
#服务地址，必要，之后统一填集团能力桥接服务网关地址
host: 127.0.0.1:30006
##定义的api的前缀，必须/开头，可以不设置该参数，建议设置
basePath: /iot/device/get
#接口分类标签，建议设置，可以定义多个，-表示是个数组元素
tags:
  - name: device
    description: 设备管理
# 指定调用接口的协议，必须是:"http", "https", "ws", "wss"．
#  -表示是个数组元素，即schemes接受一个数组参数
schemes:
  - http
#对应与http协议头request的Accept，调用者产生类型。
#默认是*/*,定义的类型必须是http协议定义的 Mime Types
#RestfulAPI一般定义成application/json
#这两个是对所有接口的全局设置
#在细化的接口中还可以对应这两个属性来覆盖全局属性
produces:
  - application/json
#必要字段!定义可操作的API
paths:
  #具体url接口调用路径（若是上文中没有设置basePath的话，这里就需要写全为/iot/device/get/test）
  /test:
    ##必要字段!定义HTTP操作方法，必须是http协议定义的方法（get、post、put、delete）
    get:
      #上面tags中定义的tag标签，方便快速过滤出某种标签下的接口
      tags:
        - device
      ##接口概要
      summary: 查询普通设备详情
      #接口描述
      description: 查询普通设备的详细信息
      #接口唯一标识，可以类似于接口的方法名
      operationId: queryDevice
      #接口产生类型，局部生效
      produces:
        - application/json
      #请求参数
      parameters:
         ##参数key，该参数为deviceId
        - name: deviceId
          ## 传递方法，formData表示表单传输，
          ##  query表示url拼接传输，
          ##  path表示作为url的一部分
          ##  body表示http头承载参数(body只能有一个,有body不能再有其他的)
          ##  一般用query（url拼接传参）、body（类似body体传参）
          in: query
          #是否必传
          required: true
          #参数类型
          type: string
          #描述
          description: 设备ID
          #是否允许传空值，默认false，可以不设置
          allowEmptyValue: false
      ##返回值描述，必要
      responses:
        ##返回的http状态码，自定义
        '200':
          description: "successful operation"
          ##描述返回值
          schema:
            ##引用在definitions下定义的ResultBean公共参数，注意此时后面不能再接description属性，因为其definitions下定义ResultBean时已经有了description属性
            $ref: "#/definitions/ResultBean"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "Not Found"
        default:
          description: "Unexpected error"
#定义公共参数
definitions:
  #参数名，可以类似于实体类的ResultBean类
  ResultBean:
    #类型：string、interger、object、array、boolean、number
    type: object
    #属性标题，建议与上面的参数名等同
    title: ResultBean
    #属性描述
    description: 接口请求返回结果
    #哪些必传字段
    required:
      - data
      - errorCode
      - errorMsg
    ##定义属性
    properties:
      #属性名，自定义的data字段
      data:
        #引用在definitions下定义的DeviceInfo公共参数
        $ref: "#/definitions/DeviceInfo"
      errorCode:
        #类型
        type: integer
        #格式
        format: int32
        description: 请求结果code
      errorMsg:
        type: "string"
        description: "请求结果描述"
  #设置参数名，可以类似于实体类的DeviceInfo类
  DeviceInfo:
    type: object
    title: DeviceInfo
    description: 设备详情
    required:
      - id
      - serialNumber
      - deviceId
      - deviceKey
      - projectCode
      - venderId
      - corporation
      - corporationText
      - model
      - modelText
      - fwVersion
      - cpVersion
      - protocolCode
      - deviceName
      - deviceType
      - ipAddr
      - port
      - status
      - acquisitionFrequency
      - isOnline
    properties:
      id:
        type: integer
        format: int64
        description: 主键ID
        #默认值设为1
        default: 1
      serialNumber:
        type: string
        description: 唯一编号或mac（不带“-”）
      deviceId:
        type: string
        description: 设备ID
      deviceKey:
        type: string
        description: 设备密钥
      projectCode:
        type: string
        description: 项目编号
      venderId:
        type: string
        description: 供应商ID
      corporation:
        type: string
        description: 厂家编号
      corporationText:
        type: string
        description: 厂家名称
      model:
        type: string
        description: 型号编号
      modelText:
        type: string
        description: 型号名称
      fwVersion:
        type: string
        description: 固件版本号
      cpVersion:
        type: string
        description: 组件版本号
      protocolCode:
        type: string
        description: 对接协议版本号
      deviceName:
        type: string
        description: 设备名称
      deviceType:
        type: string
        description: 设备类型
      ipAddr:
        type: string
        description: IP地址
      port:
        type: integer
        format: int32
        description: 端口号
      status:
        type: integer
        format: int32
        description: 状态，1：有效，9：已刪除
      acquisitionFrequency:
        type: integer
        format: int32
        description: 设备心跳频率，单位分钟，默认10分钟
        default: 10
      isOnline:
        type: integer
        format: int32
        description: 是否在线，0:不在线，1:在线
        #枚举
        enum:
          - 0
          - 1

1.1可视化界面

在这里插入图片描述

2.编写post-yaml示例

文件取名自定义，建议有标识度，以.yaml结尾，如：PersonLibraryQuery.yaml

##必要字段！Swagger规范版本，必须填2.0，否则该YAML将不能用于Swagger其他组件
swagger: "2.0"
#必要字段！描述API接口信息的元数据
info:
  #接口标题
  title: 静态人脸识别服务
  #接口文档的描述
  description: 静态人脸识别接口
  #版本号，自定义
  version: 1.0.0
#服务地址，必要，之后统一填集团能力桥接服务网关地址
host: "127.0.0.1:6061"
##定义的api的前缀，必须/开头，可以不设置该参数，建议设置
basePath: /ai/face/dataset/get
#接口分类标签，建议设置，可以定义多个，-表示是个数组元素
tags:
  - name: personLibrary
    description: 人像库接口
# 指定调用接口的协议，必须是:"http", "https", "ws", "wss"．
#  -表示是个数组元素，即schemes接受一个数组参数
schemes:
  - http
#必要字段!定义可操作的API
paths:
  #具体url接口调用路径（若是上文中没有设置basePath的话，这里就需要写全为/ai/face/dataset/get/test）
  /test:
    ##必要字段!定义HTTP操作方法，必须是http协议定义的方法（get、post、put、delete）
    post:
      #上面tags中定义的tag标签，方便快速过滤出某种标签下的接口
      tags:
        - personLibrary
      ##接口概要
      summary: 人像库查询
      #接口描述
      description: 查询人像库的详细信息
      #接口唯一标识，可以类似于接口的方法名
      operationId: queryPersonLibrary
      #接口产生类型，局部生效
      produces:
        - application/json
      #请求参数
      parameters:
        #参数key，该参数为名为params的body体
        - name: params
          ## 传递方法，formData表示表单传输，
          ##  query表示url拼接传输，
          ##  path表示作为url的一部分
          ##  body表示http头承载参数(body只能有一个,有body不能在有其他的)
          ##  一般用query（url拼接传参）、body（类似body体传参）
          in: body
          #是否必传
          required: true
          #参数描述
          description: 入参
          schema:
            #引用在definitions下定义的QueryBo公共参数
            $ref: "#/definitions/QueryBo"
      ##返回值描述，必要
      responses:
        ##返回的http状态码，自定义
        '200':
          description: "successful operation"
          schema:
            ##引用在definitions下定义的ResultBean公共参数，注意此时后面不能再接description属性，因为其definitions下定义ResultBean时已经有了description属性
            $ref: "#/definitions/ResultBean"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "Not Found"
        default:
          description: "Unexpected error"
#定义公共参数
definitions:
  #参数名，可以类似于实体类的QueryBo类
  QueryBo:
    #类型：string、interger、object、array、boolean、number
    type: object
    #属性标题，建议与上面的参数名等同
    title: QueryBo
    #属性描述
    description: 查询入参
    #哪些必传字段
    required:
      - name
      - app_id
    ##定义属性
    properties:
      #属性名，自定义的name字段
      name:
        type: string
        description: 人脸库名称
        default: renxiang
      #属性名，自定义的app_id字段
      app_id:
        type: string
        description: appid
        default: appid
      #属性名，自定义的pageSize字段
      pageSize:
        #类型
        type: integer
        #格式
        format: int32
        description: 每页显示条数
        #默认值
        default: 10
      #属性名，自定义的pageNum字段
      pageNum:
        type: integer
        format: int32
        description: 起始页
        default: 1
  #参数名，可以类似于实体类的ResultBean类
  ResultBean:
    type: object
    title: ResultBean
    description: 接口请求返回结果
    required:
      - data
      - errorCode
      - errorMsg
    properties:
      #属性名，自定义的data字段
      data:
        #类型，类似于arraylist
        type: array
        description: 请求结果数据
        #array的组成部分
        items:
          #引用在definitions下定义的PersonLibraryInfo公共参数
          $ref: "#/definitions/PersonLibraryInfo"
      #属性名，自定义的errorCode字段
      errorCode:
        type: integer
        format: int32
        description: 请求结果code
      #属性名，自定义的errorMsg字段
      errorMsg:
        type: string
        description: 请求结果描述
  PersonLibraryInfo:
    type: object
    title: PersonLibraryInfo
    description: 人像库信息
    required:
      - repositoryId
      - name
    properties:
      repositoryId:
        type: integer
        format: int64
        description: 人脸库id
      name:
        type: string
        description: 人脸库名称

2.1可视化界面

在这里插入图片描述

桃橙柳
关注
  • 0
    点赞
  • 踩
  • 3
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
专栏目录
Swagger Editor教程
benben的博客
05-09 2万+
Swagger是一个简单但功能强大的API表达工具，是目前现有的最大API工具生态系统。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。 安装 Windows上的安装 1、首先需要安装node和npm。你可以在cmd命令行看到你的安装信息。使用命令node -v和npm -v，可以用来查看版本信息。 2、安装后，还需要安装http-server。使...
Sawgger2 接口在线化文档生成 教程
loa_loa的博客
05-09 1366
前言 在做前后端分离的项目过程中，后端的接口文档更新维护的工作量很大。开发过程中接口发生变更，不仅要修改接口代码，还需要及时的修改接口文档。传统接口文档都是用word或excel进行记录编辑，而且还需要配合接口调用工具或到浏览器中进行接口的调用测试。这时候使用这套可视化，规范化的自动接口生成文档工具就会更加方便开发测试了。在工具页面中可以直接填写输入参数进行接口调用，不用再自己复制url链接去测试接口了。 总体思路 在swagger-editor中编写好了api文档，再放到swagger-ui中.
Swagger Editor 教程
最新发布
gitblog_01071的博客
08-08 913
Swagger Editor 教程 swagger-editorSwagger Editor项目地址:https://gitcode.com/gh_mirrors/sw/swagger-editor 1. 项目介绍 Swagger Editor 是一个基于浏览器的应用，允许开发者以JSON或YAML格式编辑OpenAPI（包括OpenAPI 2.0和OpenAPI 3.0.3）规范。它可以实时预...
swagger-editor：Swagger编辑器
02-04
:mantelpiece_clock: 寻找旧版的Swagger Editor？ 请参阅。 Swagger编辑器使您可以在浏览器中的YAML中编辑，并实时预览文档。 然后可以生成有效的Swagger JSON描述，并与完整的Swagger工具（代码生成，文档等）一起使用。 作为一个全新的版本，从头开始编写，存在一些已知问题和未实现的功能。 请查看“部分以获取更多详细信息。 该存储库发布到两个不同的NPM模块： 是传统的npm模块，旨在用于能够解决依赖关系（通过Webpack，Browserify等）的单页应用程序中。 是一个无需依赖的模块，其中包括在服务器端项目或无法解析npm模块依赖项的Web项目中为Swagger
swagger文档在线编辑：Swagger Editor
RayPick的博客
08-10 2354
Swagger文档编辑网址点击此处 语法请参考以下官网： 2.0：https://swagger.io/docs/specification/2-0/basic-structure/ openapi3：https://swagger.io/docs/specification/basic-structure/ Swagger Editor: Swagger提供的一个编辑器，用来通过Swagger提供的特定的YAML语法来编写API文档，打开后页面显示如下： 这里简要介绍一下文档格式： #必要字段！Swag
swagger-editor
03-19
swagger 编辑工具，Swagger简单Demo例子，
巧用 Swagger 在线编辑器生成前端接口代码
weixin_34346099的博客
07-01 2794
Swagger 简要介绍 Swagger / Open API 在Restful API 领域已慢慢成为标准，越来越多的系统使用swagger来规范开发接口文档，由于Swagger 本身并不依赖特定的语言和开发平台，所以特别合适作为前后端分离的接口标准来使用。 Swagger 官方提供了两种文档UI形式，一种是 Swagger UI, 另一种是 Swagger Editor. Swagger ...
Swagger Editor 简单入门
抱朴守拙
03-20 3504
Swagger 编辑器用来设计、定义、和文档化符合 Swagger 规范的 RESTful APIs。 1、安装 Swagger Editor 是开源工具，能在线访问，也可以本地部署，下面是本地部署的流程。 1、安装 NodeJS。 然后执行 npm install 安装 npm 所需的依赖包。 2、安装 http-server 模块 npm install -g http-server 3、...
Swagger Editor
12-04
Swagger Editor 使用YAML语言来编写API定义。YAML是一种人类可读的数据序列化格式，特别适合于配置文件和数据交换。在Swagger Editor中，你可以定义如下关键元素： 1. **info**：包含API的基本信息，如版本、标题、...
swagger-editor-validate
03-06
2. **语法高亮和错误提示**：Swagger Editor 提供了代码高亮和实时错误检测，帮助开发者在编写规范时避免语法错误。 3. **JSON/YAML 转换**：编辑器支持在 JSON 和 YAML 之间无缝切换，两者都是 OpenAPI ...
快速上手 Swagger Editor：编写高效 API 文档的完全指南
m0_73898769的博客
12-27 960
OpenAPI 规范（曾名为 Swagger 规范）作为一套广泛认可的 API 描述标准，包含了 API 的路径、参数、请求体、响应内容等信息。它是从 Swagger 发展而来，目前已获得广泛的行业支撑。标准化的描述语言：利用 YAML 或JSON描述 API 细节，包括路径、参数、请求与响应等。动态文档：可以自动生成 API 文档，支持在线测试和调试API。高可扩展性：支持添加自定义属性以满足特定业务需求。多语言支持：能够对接多种编程语言的代码生成工具。
swagger文档编写
01-31
API自动编写文档的工具swagger，API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架。
swagger-editor3
06-01
Swagger Editor 是一个强大的在线工具，用于创建、编辑和展示 Swagger JSON 或 YAML 文件，这些文件是 Swagger 规范的一部分，用于定义 RESTful API 的接口。Swagger 编辑器3是该工具的最新版本，提供了一系列改进和...
手动编写Swagger文档与部署指南
lbw520的博客
07-18 1759
Swagger介绍 在Web开发中，后端开发者在完成接口开发后，需要给前端相应的接口使用说明，所以一般会写一份API文档。一般来说，有两种方式提供API接口文档，一种是利用插件在代码中自动生成，另一种是手工编写API文档。 Swagger就是为API文档设计而生的，其中包含一整套相关工具，既支持利用插件在代码中进行注解从而自动生成文档，也支持手工编写文档。两种方式各有优缺点： 自动生成：省时，方...
swagger-editor语法
liukuan73的专栏
09-14 4312
2.0：https://swagger.io/docs/specification/2-0/basic-structure/ openapi3：https://swagger.io/docs/specification/basic-structure/
接口文档神器---Swagger使用之Swagger Editor
qq_38530648的博客
12-03 614
Swagger使用 Swagger Editor 一个开源的编辑器 进入swagger官网，选择liveDemo 基于YAML等语法定义API并自动生成文档 自动导出多种语言的服务端或客户端代码 点击Generate Client，选择java,这里是以java语言为例，生成java代码 ...
使用Swagger编写API文档指南
Swagger的流行性在于它广泛的社区支持和丰富的工具链，包括Swagger UI用于展示文档，Swagger Codegen用于生成客户端库，以及Swagger Editor用于编写和验证OpenAPI定义。 1.2 OpenAPI规范 OpenAPI规范（以前称为...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值