Redocly CLIの lint 機能 (redocly lintコマンド) を使うと OpenAPI の静的解析ができる👌
今回は redocly lintコマンドを GitHub Actions に組み込んで OpenAPI の静的解析を実行できるようにしてみた ＼( 'ω')／
OpenAPI サンプル
今回は Petstore (OpenAPI 3.0)を Swagger サイトからダウンロードして使う🐶🐱
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オプションを使って不要なビルトインルールを除外できる👌
すると警告（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 のワークフローコマンドとしてエラーと警告を出力できるため，プルリクエストに自動的にコメントできるようになる❗️
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
プルリクエストを作る
意図的に Path Parameter を削除して，ビルトインルール path-parameters-definedに該当するようにした💣️
プルリクエストを作ると GitHub Actions から自動的にコメントが入った👌便利〜
