第七天 - MetaCPAN, Mojolicious 和 OpenAPI

Fri Dec 7, 2018

在这几年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。

# 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可用的每个路径都在路径对象中定义。

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

定义参数 #

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

# 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 状态代码定义定义。

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 属性是指向文件和节的相对指针（再次用＃分隔）以包含在指定的点。

        results:
          title: Results
          type: array
          items:
            $ref: "../definitions/results.yml#/search_result_items"

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

可能为空 #

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

favorites:
  type:
    - "integer"
    - "null"

MetaCPAN 规范 #

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

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

进一步阅读 #

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

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