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 から自動的にコメントが入った👌便利〜