对于OpenApi的设计

Author Avatar
A Man Has No Name 6月 26, 2017
  • 在其它设备中阅读本文章

是不是能够统一API的设计,建立一个契约,然后各自开发呢?

一个开源的API定义

他们的目标

定义标准的、独立于语言的指向 REST API 的接口,使得服务能力无需访问源代码、文档,或是借助于网络流量检查,就可被人类和计算机发现并理解。通过对 OpenAPI 做适当定义后,消费者可使用最小数量的实现逻辑理解远程服务,并与远程服务交互。

他们的结构

对比

经典结构

创建一个测试的API test_api.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
swagger: "2.0"
info:
title: "测试API"
description: >
这里是markdown 语法
*这是用来演示基础结构的数据*
`这是`第二条 等
version: 1.0.0
host: api.example.com
basePath: /v1
schemes:
- https
- http
paths:
/users:
get:
summary: 返回一个用户列表
description: 哈哈哈哈哈,看不懂
produces:
- application/json
responses:
200:
description: OK
404:
description: 找不到呗

Mata数据

  • swagger: "2.0" , 固定的声明
  • info, 接口介绍,描述

    • title: 接口名称
    • description: 接口描述,可以使用markdown语法
    • version: 接口版本,
    • contact: 联系人
      • name: 姓名
      • url: 网址
      • email: 邮箱

        URL配置

  • host: api.example.com, 配置域名

  • basePath: /v1, 配置路由
  • schemes:
    • https, http, ws, 配置http,scheme,可以是数组

路由设置

  • paths:
    • /users, /actions 等等
      • get, post, put等 HTTP Methods
        • summary: 对这个接口,这个method的一个总结
        • description: 描述
        • produces:
          • application/json, application/xml
        • responses:
          200:
          • description: OK

            参数 Parmeters

{} 可以设置参数:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
paths:
/users/{userId}:
get:
summary: 通过uid返回一个用户信息
parameters:
- in: path
name: userId
required: true
type: integer
minimum: 1
description: 这个参数很吊
responses:
200:
description: OK

返回信息Responses

你可以根据HTTP状态码,定义信息格式。比如 200: ok404: Not Found

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
paths:
/users/{userId}:
get:
summary: 返回
parameters:
- in: path
name: userId
required: true
type: integer
minimum: 1
description: 哈哈哈
responses:
200:
description: 返回一个用户的类, 下面是描述类的结构
schema:
type: object
properties:
id:
type: integer
example: 4
name:
type: string
example: 那谁
400:
description: 呵呵
404:
description: 哈哈哈
default:
description: 哟哟哟哟哟

Models模型的定义

$ref: 可以定义一些类型,用来描述一些数据结构。

比如:

1
2
3
4
{
"id": 4,
"name": "你大爷"
}

可以定义为:

1
2
3
4
5
6
7
8
9
10
definitions:
User:
properties:
id:
type: integer
name:
type: string
required:
- id
- name:

然后,引用:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
paths:
/users/{userId}:
get:
summary: Returns a user by ID.
parameters:
- in: path
name: userId
required: true
type: integer
responses:
200:
description: OK
schema:
$ref: '#/definitions/User'

鉴权Auth

1
2
3
4
5
6
securityDefinitions:
BasicAuth:
type: basic
security:
- BaseicAuth: []

参数

  • query 参数,比如 /users?role={admin}
  • path 参数,比如 /users/{id}
  • header 参数,比如 X-MyHeader: {Value}
  • form 参数
1
2
GET /pets/findByStatus?status=available
GET /notes?offset=100&limit=50

使用in: query 来定义query

1
2
3
4
5
6
7
8
9
parameters:
- in: query
name: offset
type: integer
description: 返回数据的位移.
- in: query
name: limit
type: integer
description: 返回多少条数据.

Header Parameters

1
2
3
GET /ping HTTP/1.1
Host: example.com
X-Request-ID: 77e1c83b-7bb0-437b-bc50-a7a58e5660ac
1
2
3
4
5
6
7
8
9
paths:
/ping:
get:
summary: 检查服务是否存活.
parameters:
- in: header
name: X-Request-ID
type: string
required: true

Swagger是一个工具

我们可以使用他来解析配置,设计我们的API.