swagger

最新推荐文章于 2023-04-26 22:25:35 发布

改个名字888777

最新推荐文章于 2023-04-26 22:25:35 发布

阅读量214

点赞数

分类专栏：杂

本文链接：https://blog.csdn.net/Lakeson/article/details/89316597

版权

杂专栏收录该内容

10 篇文章 0 订阅

订阅专栏

参考文档：https://huangwenchao.gitbooks.io/swagger/content/

API的基本组成部分，包括提供给API消费者的不同HTTP请求方法、路径，请求和消息体中的参数，以及返回给消费者的不同HTTP状态及响应消息体。

swagger: "2.0"

info:
  version: 1.0.0
  title: Simple API
  description: A simple API to learn how to write OpenAPI Specification

schemes:
  - https
host: simple.api
basePath: /openapi101

paths:
  /persons:
    get:
      summary: Gets some persons
      description: Returns a list containing all persons.
      responses:
        200:
          description: A list of Person
          schema:
            type: array
            items:
              required:
                - username
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                username:
                  type: string

定义参数请求：用户太多，我们不想一股脑全部输出出来。这个时候，分页输出是个不错的选择，我们可以通过添加请求参数来实现。

定义路径参数：有时候我们想要根据用户名来查找用户信息，这时我们需要增加一个接口操作，比如可以添加一个类似 /persons/{username} 的操作来获取用户信息。注意，{username} 是在请求路径中的参数。

因为 {username} 是路径参数，我们需要先像请求参数一样将它添加到 parameters 属性中，注意名称应该同上面大括号（ { } ）里面的名称一致。并通过 in 这个属性，来表示它是一个路径（path）参数。

      parameters:
        - name: username
          in: path
          required: true
          description: The person's username
          type: string

定义消息体参数：当我们需要添加一个用户信息时，我们需要一个能够提供 post /persons 的API操作。

简化API文档：definitions

-表示是个数组元素

可以看出访问的url都很清晰的展示在swagger最终的页面上，我们打开一个方法：可以看出方法的请求参数清晰的的罗列出来，包括方法的返回值。并且有一个很重要的功能，只需要点下方的try it out就可以进行接口测试。

把之前Swagger Edit导出的swagger.json文件复制到dist文件夹里面，修改index.html的url路径，改成指向swagger.json。就可以读取json文件的内容了。

swagger try it out功能：

curl: 发送的请求参数信息 request url: 请求地址，就是发送的域名 response body: 响应内容 response code: 响应状态码 response headers: 响应头

步骤：

1 进入swagger-ui文件夹。cmd下运行$ http-server命令。
2. 进入http://127.0.0.1:8080/dist/index.html就可以看到swagger页面了

#必要字段！Swagger规范版本，必须填2.0，否则该YAML将不能用于Swagger其他组件
swagger: '2.0'
#必要字段！描述API接口信息的元数据
info:
#接口标题
title: swagger说明文档
#接口文档的描述
description: 学习Swagger
#版本号
version: 1.0.0
#Swagger会提供测试用例，host指定测试时的主机名，如果没有指定就是当前主机,可以指定端口．
host: 127.0.0.1
#定义的api的前缀，必须已/开头,测试用例的主机则为:host＋bashPath
basePath: /api
#指定调用接口的协议，必须是:"http", "https", "ws", "wss"．默认是http.-表示是个数组元素，即schemes接受一个数组参数
schemes:
- http
- https
#对应与http协议头request的Accept，调用者可接受类型,默认是*/*,定义的类型必须是http协议定义的 Mime Types,RestfulAPI一般定义成application/json
#这两个是对所有接口的全局设置，在细化的接口中是还可以对应这两个属性来覆盖全局属性
produces:
- application/json
#必要字段!定义可有可操作的API
paths:
/users:
#必要字段!定义HTTP操作方法，必须是http协议定义的方法
get:
#接口概要
summary: 查询所有用户信息
#接口描述
description: 查询出所有用户的所有信息，用户名，别名
#标签，方便快速过滤出User相关的接口
tags:
- User
#返回值描述，必要自动
responses:
#返回的http状态码
200:
description: 所有用户信息或者用户的集合信息
#描述返回值
schema:
#返回值格式，可选的有array,integer,string,boolean
type: array
#针对array,每个条目的格式,type定义为array．必要填写items
items:
#引用在definitions下定义的Users
$ref: '#/definitions/User'
#执行出错的处理
default:
description: 操作异常,执行失败.返回信息描述错误详情
schema:
#值类型
type: object
#定义属性
properties:
#属性名
message:
#类型
type: string
#即对于同一个url定义两个不同的方法，表示两个接口
post:
description: 注册一个用户
#请求参数
parameters:
#参数key
- name: username
#传递方法，formData表示表单传输，还有query表示url拼接传输，path表示作为url的一部分
#body表示http头承载参数(body只能有一个,有body不能在有其他的)
in: formData
#参数描述
description: 用户名，不能使用已经被注册过的
#参数是否必要，默认false
required: true
#参数类型，可选的包括array,integer,boolean,string.使用array必须使用items
type: string
- name: password
in: formData
description: 用户登陆密码，加密传输，加密存储
required: true
type: string
- name: alias
in: formData
type: string
description: 用户别名
#非必要字段
required: false
responses:
#返回的http状态码
200:
description: 通过返回值来标示执行结果返回true表示执行成功
schema:
#值类型
type: object
#定义属性
properties:
#属性名
status:
#类型
type: boolean
#描述
description: 是否成功
#执行出错的处理
default:
description: 操作异常,执行失败.返回信息描述错误详情
schema:
#值类型
type: object
#定义属性
properties:
#属性名
message:
#类型
type: string
/users/{id}:
#{id}表示id为请求参数，例如/users/1,/users/2都是对该API的请求，此时id即为１和2
get:
summary: 根据用户名id查询该用户的所有信息
description: 查询出某个用户的所有信息，用户名，别名等
tags:
- User
parameters:
#上面接口中定义了{id}，则参数列表中必须包含参数id,并且请求类型为path
- name: id
in: path
description: 要查询的用户的用户名,它是唯一标识
required: true
type: string
responses:
200:
description: 所有用户信息或者用户的集合信息
schema:
$ref: '#/definitions/User'
default:
description: 操作异常,执行失败.返回信息描述错误详情
schema:
#值类型
type: object
#定义属性
properties:
#属性名
message:
#类型
type: string
#http定义的delete方法,删除一个资源
delete:
summary: 删除用户
description: 删除某个用户的信息，被删除的用户将无法登陆
parameters:
- name: id
in: path
type: string
required: true
description: 用户的唯一标示符
tags:
- User
responses:
200:
description: 通过返回值来标示执行结果返回true表示执行成功
schema:
#值类型
type: object
#定义属性
properties:
#属性名
status:
#类型
type: boolean
#描述
description: 是否成功
default:
description: 操作异常,执行失败.返回信息描述错误详情
schema:
#值类型
type: object
#定义属性
properties:
#属性名
message:
#类型
type: string
#描述错误信息
#http定义的patch方法，表示修改一个资源
patch:
summary: 用户信息修改
description: 修改用户信息(用户名别名)
parameters:
- name: id
in: path
description: 用户名,要修改的数据的唯一标识符
required: true
type: string
- name: alias
in: formData
description: 新的用户别名
required: true
type: string
tags:
- User
responses:
200:
description: 通过返回值来标示执行结果返回true表示执行成功
schema:
#值类型
type: object
#定义属性
properties:
#属性名
status:
#类型
type: boolean
#描述
description: 是否成功
default:
description: 操作异常,执行失败.返回信息描述错误详情
schema:
#值类型
type: object
#定义属性
properties:
#属性名
message:
#类型
type: string
#描述错误信息
definitions:
User:
#值类型
type: object
#定义属性
properties:
#属性名
id:
#类型
type: string
#描述
description: 用户的唯一id
username:
type: string
description: 用户名
alias:
type: string
description: 别名

改个名字888777

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
swagger

参考文档：https://huangwenchao.gitbooks.io/swagger/content/API的基本组成部分，包括提供给API消费者的不同HTTP请求方法、路径，请求和消息体中的参数，以及返回给消费者的不同HTTP状态及响应消息体。swagger: "2.0"info: version: 1.0.0 title: Simple API descript...
复制链接

扫一扫

专栏目录