第七天 - MetaCPAN, Mojolicious 和 OpenAPI

img

在这几年meta :: hack 3中,我非常幸运地与Joel Berger合作,通过Mojolicious将OpenAPI与MetaCPAN API集成/记录。

它是什么?

OpenAPI是用于设计,记录,验证和驱动RESTful API的规范。它可用于为现有API提供文档,或者在创建新API时提供文档。

OpenAPI规范起源于Swagger规范,并重命名为将API描述格式(OpenAPI)与开源工具(Swagger)分开。该规范已移至新的GitHub存储库,但未更改。

对于MetaCPAN API,我们开始提供现有API的文档,但很快也转向支持API调用的验证。

工具

OpenAPI有许多可用的工具可供帮助,包括有助于编写规范的发现工具。我们选择手动编写定义(当然是vim)并使用工具生成文档并将规范集成到MetaCPAN中。

ReDoc - OpenAPI / Swagger生成的API参考文档
ReDoc创建一个交互式页面,根据OpenAPI规范文件中提供的详细信息提供文档和示例。 ReDoc包含一个HTML模板,用作静态文件,用于自定义文档的显示方式。

Mojolicious :: Plugin :: OpenAPI - Mojolicious的OpenAPI / Swagger插件
读取OpenAPI规范文件,并为基于Mojolicious的应用程序添加适当的路由和验证。

JSON :: Validator - 根据JSON模式验证数据
集成到Mojolicious :: Plugin :: OpenAPI模块中,提供输入和输出验证,以及为规范文件本身提供验证。

入门

在实现MetaCPAN OpenAPI规范时使用以下策略。

OpenAPI 规范文件

通过支持多行属性值,可以更轻松地以更少的格式进行读写,我们选择了YAML。还支持JSON。

1
2
3
4
5
6
7
8
9
# Define the version of the OpenAPI spec to use. Version 2.0 still uses
# swagger as the key
swagger: "2.0"
# general information about the API
info:
version: "1.0.0"
title: "MetaCPAN API"
# common path shared throughout the API
basePath: "/v1"

定义端点

API可用的每个路径都在路径对象中定义。

1
2
3
4
5
6
7
8
9
10
11
12
paths:
# The path to the endpoint
/search/web:
# The HTTP method that the endpoint accepts
get:
# A unique identifier for the method
operationId: search_web
# This attribute points to the name of the class in the appliction
# and the method to call separated by `#`
x-mojo-to: Search#web
# A description of the API Endpoint
summary: Perform API search in the same fashion as the Web UI

定义参数

每种方法都可以定义自己的参数。

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
30
31
32
33
34
35
36
37
# The parameters that the HTTP method accepts
parameters:
# The name of the parameter
- name: q
# The location to parse the parameter from
in: query
# Document what the parameter is. This example uses the YAML HEREDOC
# syntax to make the description easier to read and write.
description: |
The query search term. If the search term contains a term with the
tags `dist:` or `module:` results will be in expanded form, otherwise
collapsed form.

See also `collapsed`
# The type of the value that the API accepts
type: string
# Define the attribute as required
required: true
# The rest of the parameters that the API accepts
- name: from
in: query
description: The offset to use in the result set
type: integer
# If the API applies a default to an attribute if it isn't specified.
# Let the us know what it is.
default: 0
- name: size
in: query
description: Number of results per page
type: integer
default: 20
- name: collapsed
in: query
description: |
Force a collapsed even when searching for a particular
distribution or module name.
type: boolean

定义响应

OpenAPI 规范允许您定义方法调用的每个响应,包括特定和一般错误处理。根据 HTTP 状态代码定义定义。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
responses:
# HTTP 200 response
200:
description: Search response
# The schema defines what the result will look like
schema:
type: object
properties:
total:
type: integer
took:
type: number
collapsed:
type: boolean
results:
title: Results
type: array
items:
# While items can be further broken into properties per item,
# type `object` is a catch all
type: object

高级定义

通过引用重用定义

规范允许通过 JSON引用 重用。 $ref 属性是指向文件和节的相对指针(再次用#分隔)以包含在指定的点。

1
2
3
4
5
results:
title: Results
type: array
items:
$ref: "../definitions/results.yml#/search_result_items"

v2.0规范对可以使用引用的位置有限制,这会导致规范文件中的重复。 v3.0规范已经纠正了这些问题,并且还允许http引用。

可能为空

有时,对象的属性可能为 null。在 MetaCPAN API 中,收藏计数可以是表示有多少人喜欢该分发的整数,也可以是null。使用属性类型的列表允许属性包含两者。

1
2
3
4
favorites:
type:
- "integer"
- "null"

MetaCPAN 规范

为了使 OpenAPI 正常运行,整个规范不需要完整。在记录现有 API 时,可以使用 API​​ 的一部分。使用 MetaCPAN,我们从搜索端点开始。

可在此处查看 spec 文件,并在此处查看 API 文档

进一步阅读

OpenAPI 规范存储库包括完整的文档和许多不同级别的详细信息示例。

OpenAPI Map 是一个交互式站点,有助于使用 OpenAPI 规范。