Redocly CLI の lint 機能 (redocly lint コマンド) を使うと OpenAPI の静的解析ができる👌

今回は redocly lint コマンドを GitHub Actions に組み込んで OpenAPI の静的解析を実行できるようにしてみた＼( 'ω')／

OpenAPI サンプル

今回は Petstore (OpenAPI 3.0) を Swagger サイトからダウンロードして使う🐶🐱

petstore3.swagger.io

Redocly CLI

まず redocly lint コマンドを実行するとエラー（10件）と警告（13件）が出てくる😇

$ redocly lint openapi.json
No configurations were provided -- using built in recommended configuration by default.

validating openapi.json...

（中略）

❌ Validation failed with 10 errors and 13 warnings.
run `redocly lint --generate-ignore-file` to add all problems to the ignore file.

以下のドキュメントを参考に --skip-rule オプションを使って不要なビルトインルールを除外できる👌

redocly.com

すると警告（3件）まで減った❗️ちなみに redocly lint コマンドはエラーがなければ valid と表示される．

$ redocly lint openapi.json \
    --skip-rule security-defined \
    --skip-rule operation-2xx-response \
    --skip-rule operation-4xx-response
No configurations were provided -- using built in recommended configuration by default.

validating openapi.json...
[1] openapi.json:359:7 at #/components/schemas/Customer

Component: "Customer" is never used.

357 |   "xml": { "name": "order" }
358 | },
359 | "Customer": {
360 |   "type": "object",
361 |   "properties": {

Warning was generated by the no-unused-components rule.


[2] openapi.json:414:7 at #/components/requestBodies/Pet

Component: "Pet" is never used.

412 | },
413 | "requestBodies": {
414 |   "Pet": {
415 |     "description": "Pet object that needs to be added to the store",
416 |     "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } }, "application/xml": { "schema": ...<24 chars>

Warning was generated by the no-unused-components rule.


[3] openapi.json:418:7 at #/components/requestBodies/UserArray

Component: "UserArray" is never used.

416 |     "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } }, "application/xml": { "schema": ...<24 chars>
417 |   },
418 |   "UserArray": { "description": "List of user object", "content": { "application/json": { "schema": { "type": "array"...<35 chars>
419 | },
420 | "securitySchemes": {

Warning was generated by the no-unused-components rule.


openapi.json: validated in 23ms

Woohoo! Your API description is valid. 🎉
You have 3 warnings.

さらに --generate-ignore-file オプションを使うと具体的なエラー・警告レベルで除外するための .redocly.lint-ignore.yaml ファイルを自動生成してくれる👌

$ redocly lint openapi.json \
    --skip-rule security-defined \
    --skip-rule operation-2xx-response \
    --skip-rule operation-4xx-response \
    --generate-ignore-file
No configurations were provided -- using built in recommended configuration by default.

validating openapi.json...
openapi.json: validated in 15ms

Generated ignore file with 3 problems.

.redocly.lint-ignore.yaml は以下のようになっていた📝

# This file instructs Redocly's linter to ignore the rules contained for specific parts of your API.
# See https://redoc.ly/docs/cli/ for more information.
openapi.json:
  no-unused-components:
    - '#/components/schemas/Customer'
    - '#/components/requestBodies/Pet'
    - '#/components/requestBodies/UserArray'

最終的にエラーも警告もなくなった🎉

$ redocly lint openapi.json \
    --skip-rule security-defined \
    --skip-rule operation-2xx-response \
    --skip-rule operation-4xx-response 
No configurations were provided -- using built in recommended configuration by default.

validating openapi.json...
openapi.json: validated in 15ms

Woohoo! Your API description is valid. 🎉
3 problems are explicitly ignored.

GitHub Actions

次に redocly lint コマンドを GitHub Actions に組み込む．公式に提供されているアクションはなさそうだったから，シンプルに npx で実行することにした．また --format github-actions オプションを指定すると，GitHub Actions のワークフローコマンドとしてエラーと警告を出力できるため，プルリクエストに自動的にコメントできるようになる❗️

docs.github.com

name: Lint OpenAPI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Lint OpenAPI
        run: |
          npx @redocly/cli@latest lint openapi.json \
            --skip-rule security-defined \
            --skip-rule operation-2xx-response \
            --skip-rule operation-4xx-response \
            --format github-actions