inso CLIでカスタムLintingルールを適用する

小ネタ。

InsomniaでカスタムのLintingルールを適用する方法を確認した時のメモ。
なお、どこかでカスタムのLintingルールはEnterprise版でないと使えないようなものを見た記憶があるが、少なくとも今回CLIで検証した範囲ではOSS版でも利用できた。

InsomniaのLintingの仕組み

InsomniaではOpenAPI Spec(OAS)のLintingにSpectralというOSSを利用している。
これはLintingのカスタムルールをサポートしており、この仕組みを使うことでinso CLIのLintingも拡張できる。

実践

ここではサンプルとして以下のOASを利用する。

httpbin.yaml

openapi: 3.0.0
info:
  title: httpbin
  version: "0.7"
paths:
  /get:
    get:
      operationId: /get
      responses:
        "200":
          description: "get: response 200"
  /post:
    post:
      operationId: /post
      responses:
        "200":
          description: "post: response 200"
servers:
  - url: http://httpbin.httpbin.svc

カスタムのLintingルールは以下のルールによって作成する。

• Spectralのルールの拡張方法に従う
• OASと同じディレクトリに.spectral.yamlというファイル名で作成する

ここではタグ名にx-internalが含まれないとエラーとなるようなカスタムルールを作成する。
以下が作成した.spectral.yamlとなる。

.spectral.yaml

extends:
  - spectral:oas

rules:
  operation-must-have-required-tag:
    description: "全ての操作に必須タグ 'x-internal' を含めること"
    message: "必須タグ 'x-internal' がありません。"
    severity: error
    given: "$.paths[*][get,put,post,delete,options,head,patch,trace]"
    then:
      field: "tags"
      function: schema
      functionOptions:
        schema:
          type: array
          contains:
            const: "x-internal"

カスタムルール無しで実行した結果は以下。

$ inso lint spec httpbin.yaml
(node:2604537) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `inso --trace-deprecation ...` to show where the warning was created)
ℹ Using ruleset: oas, see https://meta.stoplight.io/docs/spectral/docs/reference/openapi-rules.md

 WARN  6 lint warnings found.


2:6 - Warning - info-contact - Info object must have "contact" object. - info
2:6 - Warning - info-description - Info "description" must be present and non-empty string. - info
7:9 - Warning - operation-description - Operation "description" must be present and non-empty string. - paths./get.get
7:9 - Warning - operation-tags - Operation must have non-empty "tags" array. - paths./get.get
13:10 - Warning - operation-description - Operation "description" must be present and non-empty string. - paths./post.post
13:10 - Warning - operation-tags - Operation must have non-empty "tags" array. - paths./post.post

警告が出ているが、エラーは特に出ていない。
次にカスタムルールありで実行する。

$ inso lint spec httpbin.yaml
(node:2604577) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `inso --trace-deprecation ...` to show where the warning was created)

 FATAL  2 lint errors found.



 WARN  6 lint warnings found.


2:6 - Warning - info-contact - Info object must have "contact" object. - info
2:6 - Warning - info-description - Info "description" must be present and non-empty string. - info
7:9 - Warning - operation-description - Operation "description" must be present and non-empty string. - paths./get.get
7:9 - Error - operation-must-have-required-tag - 必須タグ 'x-internal' がありません。 - paths./get.get
7:9 - Warning - operation-tags - Operation must have non-empty "tags" array. - paths./get.get
13:10 - Warning - operation-description - Operation "description" must be present and non-empty string. - paths./post.post
13:10 - Error - operation-must-have-required-tag - 必須タグ 'x-internal' がありません。 - paths./post.post
13:10 - Warning - operation-tags - Operation must have non-empty "tags" array. - paths./post.post
Errors found, failing lint.

.spectral.yamlで設定した通りにエラーが表示された。
inso CLIを使ってAPIOpsパイプラインを作成する際、プロジェクト独自のLintingを使いたい場合はこれを使うと良さそうだ。

トラブルシューティング

自環境(Mac)だと.spectral.yamlを作成したところ、以下のエラーが出た

 FATAL  Failed to read "/Users/hogehoge/work/httpbin.yaml"

これについては以下を実行することでエラーが出なくなった。

npm i @stoplight/spectral-ruleset-bundler