Swagger基础总结

The Best APIs are Built with Swagger Tools

Swagger分为四部分:

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

1.openApi规范的版本号

通过一个 swagger 属性来声明OpenAPI规范的版本。

swagger: “2.0”

2.Api描述信息:

文档相关信息

info:

version:1.0.0

title:simple api

description:a simple api to learn how to write openAPI specification

3.API的URL

作为web API,一个很重要的信息就是用来给消费者使用的 根URL ,可以用协议

(http或者https)、主机名、根路径来描述:

schemes:

-https

host: simple.api

basePath: /openapi101

意义:https://simple.api/open101

4.API的操作

4.1添加一个 路径

paths:

/persons:

4.2在路径中添加一个HTTP方法

比如需要展示一组用户信息,我们可以在 /persons 路径中添加 get 方法,同时

还可以填写一些简单的描述信息(summary)或者说明该方法的一段长篇大论

(description)。

get:

summary: Gets some persons

description: Returns a list containing all persons.

4.3定义 响应 (response)类型

对于每个方法(或操作),我们都可以在 响应 (responses)中添加任意的HTTP状

态码(比如200 OK 或者 404 Not Found等)。这个例子中我们添加上 200 的响

应:

responses:

200:

description: A list of Person

4.4定义响应内容

get /persons这个接口返回一组用户信息,我们通过响应消息中的 模

式 (schema)属性来描述清楚具体的返回内容。

一组用户信息就是一个用户信息对象的 数组 (array),每一个数组元素则是一个

用户信息 对象 (object),该对象包含三个string类型的属性: 姓氏 、 名

字 、 用户名 ,其中 用户名 必须提供(required)。

schema:

type:array

items:

    required:

        -username

    properties:

                firstName:

                      type:string

                lastName:

                        type:string

                    username:

                            type:string

4.5定义 请求参数 (query parameters)

parameters:

  • name: pageSize

in: query

description: Number of persons returned

type: integer

  • name: pageNumber

in: query

description: Page number

type: integer

4.5.1在get方法中增加请求参数

parameters:

4.5.2添加分页参数

在参数列表中,我们添加两个名字(name)分别叫

做 pageSize 和 pageNumber 的整型(integer)参数,并作简单描述:

  • name: pageSize

in: query

description: Number of persons returned

type: integer

  • name: pageNumber

in: query

description: Page number

type: integer

上一篇:sql 从另一张表取值给一张表 LEFT JOIN 关键字 sql oracle左连接


下一篇:sql之check约束