メインコンテンツまでスキップ

仕様の lint: Redocly CLI で検査して分割する

OpenAPI の章では、注文の API の仕様を openapi/openapi.yaml に書き、設計の文書と食い違わないことをテストで確かめました。テストが見るのは、仕様と文書が同じことを言っているかです。仕様の書き方そのもの (OpenAPI として正しいか、08〜10 章で決めた書き方の決まりに沿っているか) は、まだ誰も見ていません。

この章では、仕様を Redocly CLI で検査 (lint) します。組み込みの規則集で見つかるものを直し、決まりを自前の規則にし、規則が働くことをテストで確かめます。決まりと守り方を docs/api-design/guidelines.md にまとめ、仕様をファイルに分けて束ね、Redoc の文書を作ります。この章の終わりのリポジトリは、tag rest-12-r2 です。

lint で見つかるもの​

仕様の誤りを見つける手は 3 つあります。見る範囲が違うので、どれかで足りるわけではありません。

手いつ見るもの
エディタの補完と検証 (11 章)書いている最中OpenAPI の文書の形 (キーの名前・値の型)
lint (この章)保存した後と CIOpenAPI の書き方の誤りと、API の設計の決まり (キーの書き方・誤りの応答の形など)
テスト (08〜11 章)npm run test と CI仕様と設計の文書と例のファイルが同じことを言っているか

lint は、仕様が要件に合っているかは見ません。注文明細の単価を商品の今の価格から写すこと (要件の整理の章) は、どの規則にも書けません。lint が通ったことは、書き方が決まりに合っているという意味にとどまります。

Redocly CLI で仕様を検査する​

Redocly CLI の lint は、OpenAPI などの記述の問題を見つけて報告します (lint のコマンド)。このガイドでは版を 2.72.1 に固定し、npm の devDependencies に入れます。

npm install --save-dev --save-exact @redocly/cli@2.72.1

最初の lint を回す​

設定ファイルを置く前の rest-11-r2 の仕様に、そのまま当てます。設定ファイルが無いときの lint は、組み込みの規則集の recommended を使います。

Redocly CLI は、コマンドを回すたびに利用データ (回したコマンド・終了コード・CLI と Node.js の版・指摘のあった規則の名前など) を Redocly に送ります。送らないようにするには、環境変数 REDOCLY_TELEMETRY を off にするか、redocly.yaml に telemetry: off を書きます (Usage data)。この時点では redocly.yaml が無いので、環境変数を付けて回します。

REDOCLY_TELEMETRY=off npx redocly lint openapi/openapi.yaml
No configurations were provided -- using built in recommended configuration by default.

validating openapi/openapi.yaml...
[1] openapi/openapi.yaml:4:1 at #/openapi

Servers must be present.

2 | # components/examples の例は、examples/ の同じ名前のファイルと同じ値にする。
3 | # test/openapi.test.ts が、操作が対応表と、キーが表現の決まりのキーの表と一致し、例がファイルと同じでスキーマに合うことを確かめる。
4 | openapi: 3.1.2
| ^^^^^^^
5 | info:
6 | title: 注文 API

Error was generated by the no-empty-servers rule.

Reference: https://redocly.com/docs/cli/rules/oas/no-empty-servers

openapi/openapi.yaml: validated in 40ms

❌ Validation failed with 3 errors.
run `redocly lint --generate-ignore-file` to add all problems to the ignore file.

1 件ごとに、番号・場所・説明・前後の行・規則の名前と、規則の文書の URL が並びます。場所の openapi/openapi.yaml:4:1 はファイルの行と列で、#/openapi は文書の中の位置を JSON Pointer で書き、URI のフラグメントの形 (先頭に #) にしたものです。エラーの設計の章の pointer は、# を付けない形に決めたので、書き方が違います。最初の lint で出たのは、no-empty-servers (servers が無い) が 1 件と、security-defined (操作の security が無い) が 2 件でした。

端末で回すと、Redocly CLI 自身の告知の枠が出力に混ざることがあります。2.72.1 では、初めて回したときに 1 度だけ出る案内と、新しい版が出た後の版の告知です。どちらも、この章に載せた出力にはありません。止めるには、環境変数 REDOCLY_SUPPRESS_NOTIFICATIONS を true にします (2.72.0 の changelog)。changelog が挙げるのは案内だけですが、版の告知も同じ環境変数で止まることを、このガイドで試しました。

error と warn と終了コード​

規則の重さは error・warn・off の 3 つです。error が 1 件でもあると、記述は検証を通りません。warn は表示するだけで、ほかに error が無ければ記述は有効なままです (Rules の Severity settings)。

終了コードもこれに従います。servers を localhost にし、最上位に security: [] を足した rest-11-r2 の試しの仕様を、設定ファイル無しで当てました。no-server-example.com の warning が 1 件だけ出て、終了コードは 0 でした。

Warning was generated by the no-server-example.com rule.

Reference: https://redocly.com/docs/cli/rules/oas/no-server-example-com

Woohoo! Your API description is valid. 🎉
You have 1 warning.

CI は終了コードで止まるので、warning はそのままでは誰も止めません。この章の設定では、warning も error にした規則集を土台にします (後の節)。

指摘への応じ方: 仕様を直すか、規則を選ぶか​

指摘への応じ方は 3 つあります。仕様を直す、規則の重さを選ぶ、無視のファイルに書く、です。無視のファイル (--generate-ignore-file が作る .redocly.lint-ignore.yaml) は、すぐには直せない既存の API の例外を抑えるためのものです (lint のコマンド)。新しく書いている仕様で直せる指摘には使いません。最初の lint の 3 件は、どちらも仕様を直しました。

servers: 省いたときの既定を書く​

OpenAPI 3.1.2 では、servers を省くか空の配列にすると、url が / のサーバー 1 つが既定になります (4.8.1.1 節の servers)。API を置く場所はまだ決めていないので、その既定をそのまま書きました。意味は書く前と変わらず、no-empty-servers は通ります。

servers:
- url: /
description: API を置く場所はまだ決めていない。servers を省いたときの既定と同じ。

localhost を書くと、上の warning のとおり no-server-example.com に当たります。空の配列は no-empty-servers の error のままです (no-empty-servers)。

security: 操作ごとに「要らない」と書く​

security-defined は、どの操作にも、操作か仕様の最上位に security が書かれていることを求めます。資格情報の要らない公開の API でも、忘れたのではないと示すために空の security を書くよう勧めています (security-defined)。

書く場所は 2 つあります。規則の文書の例は、仕様の最上位に security: [] を書く形です。この API では、操作ごとに書きました。

post:
tags:
- orders
operationId: placeOrder
summary: 注文する
description: 商品と数量の組と連絡先メールアドレスを受け取り、注文を受付の状態で作る。商品の今の価格を単価として注文明細に写し、合計と消費税額を求め、在庫を引き当てる。
security: []

理由は 2 つです。

  • 後で足した操作を見張れる。最上位に security があると、この規則は操作ごとには確かめません。最上位に security: [] を置いたまま security の無い操作を足しても、lint は通りました。操作ごとに書いた仕様に security の無い操作を足すと、security-defined の error になります。最上位に書き足すことは、自前の規則で止めます (自前の規則の節)
  • 「認証が要らない」を言い切れる。OpenAPI 3.1.2 で、操作の空の security は、その操作から最上位の宣言を取り除きます (4.8.10.1 節の security)。最上位の一覧は不完全でよく、空でも省略してもよいとされています (4.8.1.1 節の security)。最上位の空の一覧は、認証が無いことの宣言として読めません

認証を任意にする書き方 (security: [{}]、匿名でのアクセスにも応じる) とは別のものです (4.8.30 節の Security Requirement Object)。この API の 1 周目には認証そのものが無いので、空の配列を選びました。

redocly.yaml で規則を選ぶ​

規則の選び方は、リポジトリの root の redocly.yaml に書きます。extends で組み込みの規則集を取り込み、rules で規則を足したり重さを変えたりします。後に書いた設定が、取り込んだ規則集を上書きします (設定ファイルの extends)。

lint の --extends が受ける組み込みの規則集は 4 つです (lint のコマンドの Extend configuration)。性格は Rules の Rulesets の説明によります。

規則集性格
specOpenAPI の仕様にできるだけ忠実に従う
minimal既存の API 向けで、error になる規則が少ない
recommendedRedocly が「良い API」と考える形。設定ファイルが無いときの既定
recommended-strictrecommended と同じ規則で、warning をすべて error にしたもの

この API は recommended-strict を土台にしました。recommended のままだと、例とスキーマの食い違い (no-invalid-media-type-examples) やタグの説明の欠け (tag-description) が warning にとどまり、終了コード 0 で CI を通ります。rest-11-r2 の仕様に servers と security を足した後は、recommended-strict でも指摘は 0 件でした。

extends:
- recommended-strict

rules:
rule/property-names-camel-case:
subject:
type: SchemaProperties
assertions:
casing: camelCase
message: スキーマのキーは camelCase で書く ({{problems}})
# ...
telemetry: off

rules の rule/ で始まる名前が自前の規則です (次の節)。telemetry: off は、最初の lint で付けた環境変数と同じく利用データを送らない設定で、build-docs が作るページにも効きます (build-docs の節)。

組み込みの paths-kebab-case (パスのセグメントを kebab-case にする) は、recommended で off のまま使いません。この規則は /orders/{orderId}:cancel のようなカスタムメソッドの形も error にしました。標準のメソッドで表せない操作の形は、後の周回で比べて決めるので、比べる前に規則で片方を塞がないようにしました。

npm run lint と、規則の名前の綴り違い​

lint は npm の script にしました。

npm run lint
> rest-api-order@0.0.0 lint
> redocly lint openapi/openapi.yaml --lint-config=error

validating openapi/openapi.yaml...
openapi/openapi.yaml: validated in 35ms

Woohoo! Your API description is valid. 🎉

所要時間は実行のたびに変わるので、リポジトリのテストと照合する出力では、35ms のような決まった値に置き換えて載せています。照合しない抜粋 (最初の lint の出力など) は、測った値のままです。

--lint-config=error は、設定ファイルそのものの問題の重さを error にします。既定は warn です (lint のコマンドの Lint config file)。自前の規則で subject のノード型の名前を綴り違えると、既定のままでは設定ファイルの warning が出るだけで、その規則が何も確かめずに lint が通ることがあります。SchemaProperties を SchemaProperty と綴った設定では、キーを snake_case にした仕様でも終了コード 0 で通りました。error にしておけば、lint は設定の誤りとして終了コード 2 で止まります。

自前の規則を書く: configurable rule​

組み込みの規則で足りない決まりは、redocly.yaml の中に configurable rule として書きます。名前は rule/ で始め、subject (どのノードの何を見るか) と assertions (何が成り立つべきか) を書きます。assertion が成り立たないと、message の文で報告します (configurable rules)。

operationId とキーは camelCase​

rule/operation-id-camel-case:
subject:
type: Operation
property: operationId
assertions:
casing: camelCase
message: operationId は camelCase で書く ({{problems}})

subject の type は OpenAPI のノード型で、property はそのノードの中のどの値を見るかです。キーの camelCase の規則 (上の redocly.yaml の抜粋) は property を書いていません。property を省くと、assertion はノードのキーの名前に当たります。SchemaProperties はスキーマの properties のノードなので、キーの名前、つまり JSON のキーが camelCase かを見ます。

この規則は、注文の表現だけでなく、誤りの応答の拡張メンバー (productIds・trackingId) を含む、仕様のすべてのスキーマのキーに当たります。表現の決まりの「キーは camelCase」を、API 全体の決まりとして当てました。

201 の応答の Location​

リソースを作る操作の 201 は、Location ヘッダで作ったリソースの URL を返します (リソースの設計の章)。

# headers の値を schema で確かめる。HeadersMap を subject にすると、headers の無い応答を訪ねず落とせない。
rule/created-has-location:
subject:
type: Response
property: headers
filterInParentKeys:
- '201'
assertions:
defined: true
schema:
type: object
required:
- Location
message: 201 の応答は Location ヘッダで作ったリソースの URL を返す

filterInParentKeys は、親のキーが挙げた値のノードだけに絞ります。応答のノードの親のキーはステータスコードなので、'201' で 201 の応答だけを見ます。defined: true は headers があることを、schema は headers の値が Location のキーを持つことを確かめます。schema の assertion は、値を JSON Schema (2020-12) で検証します (configurable rules の schema の例)。

ヘッダの集まりのノード型 (HeadersMap) を subject にして、required: [Location] を求める書き方もあります。この形は、headers ごと書き忘れた応答を落とせませんでした (終了コード 0)。headers の無い応答には、ヘッダの集まりのノードが無く、規則が訪ねる先が無いためです。required の assertion は property と一緒に使えない (設定の誤りになる) ので、応答のノードの headers に required を当てることもできません。

規則に反した仕様では、こう落ちます。

npx redocly lint test/fixtures/lint/rule-created-has-location/other-header.yaml
validating test/fixtures/lint/rule-created-has-location/other-header.yaml...
[1] test/fixtures/lint/rule-created-has-location/other-header.yaml:36:13 at #/paths/~1orders/post/responses/201/headers

201 の応答は Location ヘッダで作ったリソースの URL を返す

34 | description: 注文を受け付けた。
35 | headers:
36 | Content-Location:
| ^^^^^^^^^^^^^^^^^
37 | description: 作った注文の URL。
| ^^^^^^^^^^^^^^^^^^^^^^^^
… | < 2 more lines >
40 | type: string
| ^^^^^^^^^^^^
41 | content:
42 | application/json:

Error was generated by the rule/created-has-location rule.


test/fixtures/lint/rule-created-has-location/other-header.yaml: validated in 35ms

❌ Validation failed with 1 error.
run `redocly lint --generate-ignore-file` to add all problems to the ignore file.

test/fixtures/lint/ は、規則ごとに作った落ちる例の置き場です (後の節)。この例は、ヘッダの名前を Content-Location にしてあります。schema は合わない値の位置で報告するので、headers の値に印が付きます。

規則はヘッダの名前を Location の綴りどおりに探すので、location と書いても落ちます。HTTP のヘッダの名前は大文字と小文字を区別しませんが、この API の仕様では Location と書くことにしました (docs/api-design/guidelines.md のエンドポイントの表の注記)。

誤りの応答の本文​

エラーの設計の章で、誤りの応答は 4xx も 5xx も、本文に問題の詳細 (application/problem+json) を返すと決めました。これは 2 つの規則にしました。誤りの応答に本文 (content) があることと、本文のメディアタイプが application/problem+json だけであることです。

# 誤りの応答の 2 つの規則は、範囲のキー (4XX・5XX) にも当てる。default は成功の応答も兼ねうるので当てない。
rule/error-responses-have-content:
subject:
type: Response
property: content
matchParentKeys: /^[45](\d\d|XX)$/
assertions:
defined: true
message: 誤りの応答 ({{key}}) は、本文に問題の詳細を返す

# enum はキーが 0 個の content: {} を通すので、required で application/problem+json があることも求める。
rule/error-responses-problem-json:
subject:
type: MediaTypesMap
where:
- subject:
type: Response
matchParentKeys: /^[45](\d\d|XX)$/
assertions:
defined: true
assertions:
enum:
- application/problem+json
required:
- application/problem+json
message: 誤りの応答の本文は application/problem+json の問題の詳細にする ({{problems}})

matchParentKeys は、親のキーに正規表現を当てて絞ります。OpenAPI 3.1.2 では、応答のキーに大文字の X で範囲を書けるので (4XX は 400〜499、4.8.16.2 節)、正規表現は 404 の形と 4XX の形の両方に当てました。where は、subject のノードの祖先に条件を付けます。2 つ目の規則は「誤りの応答の中のメディアタイプの集まり」に絞り、キーが application/problem+json だけで、それが必ずあることを求めます。

落ちる例は、4 つの場所に置きました。応答に直に書いた 404、範囲のキーの 4XX と 5XX、components/responses に置いて $ref で指した 500 です。2 つの規則は、どれでも落ちました。default の応答は、成功の応答も兼ねうるので、どちらの規則も当てません。

2 つの規則が見るのは、本文があることとメディアタイプのキーまでです。本文のスキーマが問題の詳細の形か (Problem.yaml を allOf に持つか。oneOf のスキーマなら、どの枝の型も持つか) は見ません。在庫不足の問題のスキーマから Problem.yaml を外しても、lint とテストは通りました。スキーマの形は、ガイドラインで「人が見る」にしました。

組み込みの規則にも operation-4xx-problem-details-rfc7807 があります。この規則は 4xx の応答だけを見て、名前もリンク先も、RFC 9457 の前の版の RFC 7807 です (operation-4xx-problem-details-rfc7807)。500 の応答も同じ形にするので、自前の規則にしました。

範囲のキーは大文字の X で書く​

OpenAPI 3.1.2 が範囲のキーに認めるのは、大文字の X の 1XX〜5XX だけです (4.8.16.2 節)。小文字の 4xx は Redocly CLI の構造の検査を通り、上の 2 つの規則の正規表現 (XX) にも当たらないので、誤りの応答の規則の外に抜けます。そこで、範囲のキーの小文字を落とす規則を足しました。Responses は応答のキーの集まりのノード型で、notPattern はそのキーに当たります。

# 範囲のキーは大文字の X で書く (OpenAPI 3.1.2 の Responses Object)。小文字の 4xx は構造の検査を通り、
# 上の 2 つの規則の範囲のキーにも当たらないので、誤りの応答の規則の外に抜ける。
rule/response-range-key-uppercase:
subject:
type: Responses
assertions:
notPattern: /^[1-5](xx|xX|Xx)$/
message: 範囲のキーは大文字の X で書く ({{problems}})

スキーマの example を使わない​

rule/schema-no-example:
subject:
type: Schema
property: example
assertions:
defined: false
message: スキーマの例は、非推奨の example でなく examples に書く

OpenAPI 3.1.2 は、スキーマの example を非推奨にし、JSON Schema の examples を使うよう勧めています (4.8.24 節の example)。非推奨でも仕様に反するわけではなく、recommended-strict の規則もスキーマの example を指摘しません。

このリポジトリのテストの検証器 (Ajv の JSON Schema 2020-12 の検証器) は、example を知らないキーワードとして誤りにします。components/schemas の部品に example を足すと、仕様のテストが 2 件落ちました。後の部で使うサーバーの検証器も、リクエストのスキーマに example があると起動しないことを、このガイドで試しました。lint で書いた時点に止めるほうが、原因を探しやすくなります。

パラメータ・ヘッダ・メディアタイプの example は非推奨でなく、OpenAPI の章のテストも読むので、規則はスキーマの example だけに当てました。

最上位に security を書かない​

security の節で、認証の要らない操作には操作ごとに security: [] を書くと決めました。最上位に security を書くと、security-defined は操作ごとに確かめなくなります。そこで、最上位の security を規則で止めます。

# 最上位に security があると、組み込みの security-defined は操作ごとに確かめなくなる。
rule/root-no-security:
subject:
type: Root
property: security
assertions:
defined: false
message: 認証の要らない操作の security は、最上位でなく操作ごとに書く

Root は文書の最上位のノード型です (inspect-node-types で #/ を引くと Root と出ます。次の節)。defined: false は、security が無いことを求めます。この規則と security-defined の 2 つで、操作の security の書き忘れも、最上位への書き足しも、lint が落とします。

規則を書く前に、ノード型を調べる​

subject に書くノード型の名前 (SchemaProperties・MediaTypesMap・Root など) は、仕様の見た目からは分かりません。Redocly CLI の inspect-node-types は、記述の各箇所に割り当てたノード型を表示します。--pointer で 1 か所を引き、--parents を付けると、ルートからそこまでのノード型の連なりが出ます。この連なりが where に書く祖先の語彙になります (inspect-node-types)。実験的な機能なので、出力の形は版で変わりえます。

用語集の使わない語を規則にする​

ドメインを探るの章で、用語集を作り、docs/ の文書に用語集の使わない語が無いことをテストで確かめました。同じ確かめを、仕様の title・summary・description にも lint で掛けます。

# 用語集 (docs/glossary.yaml) の avoid の語。その語を含む用語集の語と allowed の語 (消費税額・ユーザーストーリー・ユーザーエージェント) は、後読みと先読みで外す。
# test/glossary.test.ts が、avoid の語がどれもこの正規表現に当たり、外す語が当たらないことを確かめる。
rule/glossary-avoid:
subject:
type: any
property:
- title
- summary
- description
assertions:
notPattern: /OrderItem|Stock|税込価格|売価|(?<!消費)税額|外税|キャンセル|補充|restock|顧客|購入した人|ユーザー(?!ストーリー|エージェント)|エラー ID/
message: 用語集の使わない語がある ({{problems}})。docs/glossary.yaml の avoid を見る

type: any はどのノードにも当て、property に挙げた値を見ます。05 章のテストは、使わない語を探す前に、その語を含む用語集の語 (「税額」を含む「消費税額」) と allowed の語 (「ユーザー」を含む「ユーザーストーリー」) を消していました。正規表現では、それを後読み ((?<!消費)) と先読み ((?!ストーリー|エージェント)) で写しました。

npx redocly lint test/fixtures/lint/rule-glossary-avoid/summary.yaml
validating test/fixtures/lint/rule-glossary-avoid/summary.yaml...
[1] test/fixtures/lint/rule-glossary-avoid/summary.yaml:20:16 at #/paths/~1orders/post/summary

用語集の使わない語がある ("顧客が注文する" should not match a regex /OrderItem|Stock|税込価格|売価|(?<!消費)税額|外税|キャンセル|補充|restock|顧客|購入した人|ユーザー(?!ストーリー|エージェント)|エラー ID/)。docs/glossary.yaml の avoid を見る

18 | tags: [orders]
19 | operationId: placeOrder
20 | summary: 顧客が注文する
| ^^^^^^^
21 | security: []
22 | requestBody:

Error was generated by the rule/glossary-avoid rule.


test/fixtures/lint/rule-glossary-avoid/summary.yaml: validated in 35ms

❌ Validation failed with 1 error.
run `redocly lint --generate-ignore-file` to add all problems to the ignore file.

語の一覧は、用語集と redocly.yaml の 2 か所に置くことになります。用語集から規則を作るスクリプトにする手もありますが、作り直し忘れを止める仕組みがまた要ります。ここでは正規表現を手で写し、test/glossary.test.ts が「用語集の使わない語がどれも正規表現に当たり、外す語は当たらない」ことを確かめる形にしました。用語集に語を足して正規表現を直し忘れると、このテストが落ちます。

lint とテストで、見る範囲が違います。

確かめ見るもの見ないもの
lint の rule/glossary-avoid仕様の title・summary・description$ref と並べた description、YAML のコメント、キーの名前
test/glossary.test.tsdocs/ の文書と、仕様のファイルの文字 (コメントを含む)キーの名前を語として読むこと (orderItems のような部分一致は通る)

$ref と並べた description (注文の表現の total など) は、lint の規則に当たりませんでした。そのためテストは、仕様のファイルも文字として探します。キーの名前は、camelCase の規則と、キーを用語集の code と照らすテスト (表現の設計の章) が受け持ちます。テストが仕様のスキーマのキーと照らすのは、注文するのリクエストと注文の表現だけです。誤りの応答の拡張メンバーのキーは、ガイドラインで「人が見る」にしました。大文字と小文字・全角と半角の揺れは、05 章のテストと同じく捕まえません。

例がスキーマに合うかを確かめる​

recommended-strict では、例がスキーマに合うかを見る 3 つの規則が error になります。

  • no-invalid-media-type-examples: メディアタイプの例を見る (no-invalid-media-type-examples)
  • no-invalid-parameter-examples: パラメータの例を見る。この API の仕様では、注文 ID のパスのパラメータの例に当たる (no-invalid-parameter-examples)
  • no-invalid-schema-examples: スキーマの例を見る

11 章のテストも、名前付きの例をスキーマで検証しています。lint とテストは役割を分けて残しました。

確かめ受け持つこと
lint (例の 3 つの規則)仕様を書いている人に、合わない例を位置つきで返す
11 章のテスト例が examples/ のファイルと同じ値であること、どの例もどこかに置かれていること、後の部のサーバーと同じ検証器 (Ajv) で合うこと

lint だけにすると、例のファイルと仕様の例の食い違いを誰も見ません。テストだけにすると、合わない例の場所が分かるのは npm run test を回した後で、出力の位置も仕様の行ではありません。

規則が落ちることをテストで確かめる​

自前の規則は、書き方を誤っても lint が通ることがあります。ノード型の名前の綴り違いは、--lint-config=error を付けた lint なら設定の誤りとして止まります。止まらないのは、設定としては正しい形の誤りです。このガイドでは、次の 3 つを試しました。

  • where の祖先のノード型を誤る (応答のノード型でなく、子のメディアタイプのノード型にする)
  • 親のキーの絞り (filterInParentKeys) を、どの応答にも無いステータスコードにする
  • 親のキーに当てる正規表現 (matchParentKeys) を狭めすぎる

どれも、規則は当たるべき場所に当たらないまま、npm run lint が通りました。仕様に lint を当てて通ったことは、規則が働いている証になりません。そこで、その規則だけに反する小さな仕様を置き、落ちることをテストで確かめます。

置き場は test/fixtures/lint/ です。どの規則にも当たらない土台 (valid.yaml) を 1 つ置き、規則の名前の / を - にしたディレクトリに、土台の 1 か所 (1 つの応答・スキーマ・値) だけを変えたファイルを置きます。ファイル名は変えた所の名前です。1 つの規則が見る場所や assertion が複数あるときは、その分だけ置きます。誤りの応答の規則なら、応答に直に書いた 404・範囲のキーの 4XX と 5XX・$ref で指した 500 の 4 つです。404 の例だけだと、正規表現を 404 の形だけに狭めても、テストは通ります。201 の規則なら、headers が無い例 (defined に当たる)、ヘッダの名前が違う例 (schema に当たる)、components/responses に移して $ref で指した 201 の headers が無い例の 3 つです。

# lint の落ちる例: rule/created-has-location だけに当たる。../valid.yaml から、201 の応答のヘッダの名前を Content-Location にした。
openapi: 3.1.2
# ...
'201':
description: 注文を受け付けた。
headers:
Content-Location:
description: 作った注文の URL。

test/lint.test.ts は、4 つを確かめます。

  • 落ちる例の置き場の読み方。規則のディレクトリの YAML のファイルを規則と結び、ドットで始まる名前は読まない。規則のディレクトリの外のファイル・YAML でないファイル・規則のディレクトリの下のディレクトリは、例外にする (置き場を誤った落ちる例を、黙って読み落とさないため)
  • 土台の仕様は、どの規則にも当たらない (終了コード 0)
  • 落ちる例は、それぞれディレクトリの名前の規則だけに当たって落ちる (終了コード 1)。ほかの規則に当たると、規則どうしが重なっているか、落ちる例が別の場所も変えている
  • redocly.yaml の自前の規則には、どれも落ちる例がある

落ちる例は 26 個です。自前の規則 9 本と、この API の決まりを直に守る組み込みの規則 5 本 (security-defined・no-empty-servers と、例の 3 つの規則) の分を置きました。テストのコードは、章末の「この章のテストのコード」に載せます。

API の設計のガイドライン​

08〜10 章で決めた決まりは、エンドポイント・表現・誤りの応答の 3 つの文書に分かれています。新しい操作を足すときに、どの決まりを当て、どれが道具で守られているかを、1 か所で見られるようにしました。それが docs/api-design/guidelines.md です。

## 仕様の書き方

この文書で決めた規約。

| 規約 | 決めた文書 | 守り方 |
| --- | --- | --- |
| `servers` を書く。API を置く場所はまだ無いので `/` (省いたときの既定と同じ) にする | この文書 | lint: `no-empty-servers` / 人が見る |
| 認証の要らない操作には、操作ごとに `security: []` を書く。最上位には書かない | この文書 | lint: `security-defined` / lint: `rule/root-no-security` |
<!-- ... -->
## エンドポイント

| 規約 | 決めた文書 | 守り方 |
| --- | --- | --- |
| パスのセグメントは小文字の英語にし、2 語以上なら `-` でつなぐ | `endpoints.md` の名前の決まり | 人が見る |

決めた方針は 3 つです。

  • 置き換えずに指す。規約の本文と理由は 08〜10 章の文書に残し、ガイドラインは規約を 1 行ずつ並べて、決めた文書を指します。08〜10 章の文書の表はテストが読んでいるので、ガイドラインに写すと、同じ決まりが 2 か所に書かれて食い違いうるようになります。この章で新しく決めた仕様の書き方 (servers・security・スキーマの example など) だけは、ガイドラインを正本にし、理由も書きました
  • 守り方を書く。守り方は、lint の規則・テスト・人が見る、の 3 つです。test/guidelines.test.ts が、表の lint の規則と、落ちる例を置いた規則が 1 対 1 で、表のテストの it が実在することを確かめます。止めた it (it.skip・it.todo) と、止めた describe の中の it は、実在に数えません。規則やテストの名前を変えて表を直し忘れると、このテストが落ちます
  • 型の正本は仕様のスキーマ。表現の決まりのキーの表には型の列があり、仕様のスキーマにも型があります。型と、スキーマで書ける範囲 (注文明細の上限・税率の候補など) は、仕様のスキーマを正本にしました。キーの表の型の列は、読む人のための要約です。スキーマに書かない決まり (注文 ID の形、同じ商品の注文明細を 1 つまでにすること) は、表現の決まりを正本のままにしました。これに合わせて、09 章のテストは、上限の 100 と税率の 8・10 をコードに書かず、仕様から読むようにしました。値をテストに書き写しても落ちるテストは無いので、この行の守り方は「人が見る」です

ガイドラインで「標準のメソッド」の意味も定めました。08 章の名前の決まりにある「標準のメソッドで表せる操作では、パスに動詞を入れない」の標準のメソッドは、Google の AIP-121 の標準メソッド (取得・一覧・作成・更新・削除) を指します (AIP-121)。名前の決まりは、後の周回で足す操作にも当てます。

ガイドラインの「人が見る」の行は、道具が見ないので、仕様を直す変更の見直しのときに上から当てます。

仕様を分割する: split​

1 つのファイルの仕様は、操作や部品が増えると長くなり、変更の差分も読みにくくなります。Redocly CLI の split は、参照されている部分を別のファイルに切り出し、複数のファイルの構成にします (split)。

npx redocly split openapi/openapi.yaml --outDir openapi
find openapi -name '*.yaml' | LC_ALL=C sort
openapi/components/examples/insufficient-inventory.yaml
openapi/components/examples/internal-error.yaml
openapi/components/examples/invalid-request.yaml
openapi/components/examples/not-acceptable.yaml
openapi/components/examples/order-not-found.yaml
openapi/components/examples/order.yaml
openapi/components/examples/place-order-request.yaml
openapi/components/examples/unknown-product.yaml
openapi/components/examples/unsupported-media-type.yaml
openapi/components/responses/InternalError.yaml
openapi/components/responses/NotAcceptable.yaml
openapi/components/schemas/Amount.yaml
openapi/components/schemas/ContactEmail.yaml
openapi/components/schemas/InsufficientInventoryProblem.yaml
openapi/components/schemas/InternalErrorProblem.yaml
openapi/components/schemas/InvalidRequestProblem.yaml
openapi/components/schemas/NotAcceptableProblem.yaml
openapi/components/schemas/Order.yaml
openapi/components/schemas/OrderId.yaml
openapi/components/schemas/OrderLine.yaml
openapi/components/schemas/OrderNotFoundProblem.yaml
openapi/components/schemas/PlaceOrderBadRequestProblem.yaml
openapi/components/schemas/PlaceOrderRequest.yaml
openapi/components/schemas/Problem.yaml
openapi/components/schemas/ProductId.yaml
openapi/components/schemas/Quantity.yaml
openapi/components/schemas/UnknownProductProblem.yaml
openapi/components/schemas/UnsupportedMediaTypeProblem.yaml
openapi/openapi.yaml
openapi/paths/orders.yaml
openapi/paths/orders_orderId.yaml

LC_ALL=C は、並べ順をロケールに依らないようにするためです。macOS 26 の sort では、en_US.UTF-8 と ja_JP.UTF-8 のロケールで、orders.yaml と orders_orderId.yaml の順が入れ替わりました。

入口の openapi.yaml には、文書の情報とパスの一覧が残り、パスごとの中身を paths/ のファイルで指します。

paths:
/orders:
$ref: paths/orders.yaml
# Path Item の $ref は URI の形にする (OpenAPI 3.1.2 の MUST) ので、ファイル名にはパスの変数の {} を入れない。
/orders/{orderId}:
$ref: paths/orders_orderId.yaml

split の後に、手で 3 つを直しました。

  • パスのファイル名。split は /orders/{orderId} のファイルを orders_{orderId}.yaml と名付けました。Path Item の $ref の値は URI の形でなければなりません (4.8.9.1 節の $ref)。URI のパスに書ける文字に { と } は入らず、書くにはパーセントエンコード (%7B・%7D) が要るので (RFC 3986 の付録 A)、外した名前に変えました
  • 入口の先頭のコメント。split は YAML のコメントをすべて落とします。分けた構成と、束ねた出力の扱いを書き直しました
  • 説明の書き方。split は info.description の | (改行を残す書き方) を > (折り返す書き方) に書き換えます。値は同じでしたが、読みやすい | に戻しました

分けた後の仕様を束ねると、分ける前の仕様と値が一致しました (YAML として読んだ値を比べました)。

分けると失うものもあります。1 つのファイルで済んでいた検索や置き換えが、ファイルをまたぎます。OpenAPI の章のエディタの補完は、カタログが openapi.yaml というファイル名にスキーマを結ぶ、という読みでした。paths/ と components/ のファイルはこの名前でなく、中身も文書の一部なので、同じ関連づけには当たらないと読めます (試してはいません)。このガイドの仕様は、2 周目以降で操作と部品が増えるので、今のうちに分けました。

束ねる: bundle と dist/​

多くの道具は、1 つのファイルの仕様を読みます。bundle は、入口から $ref をたどり、参照先を 1 つのファイルにまとめます (bundle)。束ねた出力の $ref は、どれも同じファイルの中の #/components/... を指します。

npm run bundle
> rest-api-order@0.0.0 bundle
> redocly bundle openapi/openapi.yaml --output dist/openapi.yaml

bundling openapi/openapi.yaml...
📦 Created a bundle for openapi/openapi.yaml at dist/openapi.yaml 12ms.

束ねた出力 (dist/) は、リポジトリに置きません (dist/ は 1 章の時点から .gitignore に入っています)。置くと、元のファイルを直して束ね直し忘れたときに、lint と元を読むテストは通ったまま、束ねた出力を読む道具 (モックなど) だけが古い仕様で動くからです。

読むもの読み方
lint (npm run lint)分けた入口 (openapi/openapi.yaml)。$ref の先のファイルの行で指摘を出す
テスト (test/support/openapi.ts)テストの中で一時のファイルに束ねてから読む。dist/ は読まない
Swagger UI の配信 (npm run docs:swagger)起動の前に束ね、dist/openapi.yaml を配る
Redoc の文書 (npm run docs:build)束ねてから dist/openapi.yaml を読む
モック (次の章)束ねてから dist/openapi.yaml を読む

テストが dist/ を読まないのは、上の束ね直し忘れと同じ理由です。テストの読み込みは、テストを回すたびに束ねます。

Swagger UI の配信の扱いが、11 章から 1 つ変わります。11 章では、仕様のファイルを直してブラウザで読み込み直せば、画面に出ました。今は配信のサーバーが dist/openapi.yaml を配るので、openapi/ を直したら npm run bundle を回してから読み込み直します。dist/openapi.yaml が無いときは、サーバーは止まらずに 500 を返します。

build-docs で文書を作って見る​

build-docs は、仕様から Redoc の文書の HTML を 1 つ作ります (build-docs)。npm の script にしました。

npm run docs:build

作った dist/docs/index.html をブラウザで開いた画面です (Redocly CLI 2.72.1 の build-docs が使う Redoc 3.0.1 で撮りました)。

Redoc の文書の最初の画面。左に操作の一覧、中央に API の説明、右に License と Servers の欄がある

Redoc の文書の注文するの操作。リクエストの本文のキーと型と範囲、応答のステータスコード、リクエストの例が並ぶ

仕様を直しながら見るときは、npm run docs:build を回し、ブラウザで開き直します。Redocly CLI の 1 系にあった preview-docs は 2 系で無くなり、2 系の preview は Redocly のプロジェクト (Redocly の製品のパッケージで作るサイト) をプレビューするコマンドです (preview)。仕様のファイル 1 つを見る用途には、build-docs で作り直す形になります。

build-docs が作るページは、Redoc のスクリプトを Redocly の CDN から読み込みます。ネットにつながらない所で開くか、ページを人に渡すときは、--inlineBundle でスクリプトを埋め込めます。ページは閲覧者のブラウザから Redoc の利用状況を送る作りで、redocly.yaml の telemetry: off でビルドすると止まります (作ったページの設定が disableTelemetry: true になりました)。

npm run verify と CI に lint を足す​

"scripts": {
"typecheck": "tsc",
"test": "vitest run",
"lint": "redocly lint openapi/openapi.yaml --lint-config=error",
"verify": "npm run typecheck && npm run test && npm run lint",
"bundle": "redocly bundle openapi/openapi.yaml --output dist/openapi.yaml",
"docs:build": "npm run bundle && redocly build-docs dist/openapi.yaml --output dist/docs/index.html",
"docs:swagger": "npm run bundle && node tools/swagger-ui/server.ts"
},

npm run verify は、型の検査・テスト・lint の順に回します。CI の設定 (.github/workflows/ci.yml) は npm run verify を回しているので、変えていません。lint の終了コードは、指摘が無いか warning だけなら 0、error があれば 1 です。設定ファイルの形の誤り (知らないノード型の名前など) は、--lint-config=error のとき 2 になります。規則を組むときに見つかる誤り (required と property の組) は、--lint-config=error を付けても 1 で、JSON の出力も出ませんでした。

.npmrc に update-notifier=false を書きました。npm の新しい版の告知が、記事に載せた npm run の出力に混ざらないようにするためです。Redocly CLI 自身の告知は、この設定では止まりません (最初の lint の節の環境変数で止めます)。

Spectral と比べる​

OpenAPI の lint の道具には、Stoplight の Spectral もあります。同じ 4 つの決まり (operationId とキーの camelCase・201 の Location・誤りの応答の本文) を Spectral の ruleset で書き、Spectral 6.17.0 で、この 4 つの分の落ちる例 15 個と土台に当てました。落ちる例はどれも 1 件の error で落ち、土台は通りました。

rules:
operation-id-camel-case:
description: operationId は camelCase で書く
severity: error
given: $.paths[*][get,put,post,delete,options,head,patch,trace]
then:
field: operationId
function: casing
functionOptions:
type: camel

property-names-camel-case:
description: スキーマのキーは camelCase で書く
severity: error
given: $..properties
then:
field: '@key'
function: casing
functionOptions:
type: camel

created-has-location:
description: 201 の応答は Location ヘッダで作ったリソースの URL を返す
severity: error
given: $.paths[*][*].responses['201']
then:
field: headers.Location
function: truthy

error-responses-problem-json:
description: 誤りの応答の本文は application/problem+json の問題の詳細にする
severity: error
given: $.paths[*][*].responses[?(@property.match(/^[45](\d\d|XX)$/))]
then:
field: content
function: schema
functionOptions:
schema:
type: object
minProperties: 1
propertyNames:
const: application/problem+json

Spectral の規則は、given (JSONPath で対象を指す) と then (当てる関数) で書きます (Spectral の rule)。then の field は、対象の中のたどった先の値を見るので、headers.Location の 1 本で「headers が無い」と「Location が無い」の両方を落とせました。Redocly では、同じことを schema の assertion で headers の値に当てて書きました。誤りの応答は、Spectral では 1 本の schema で本文の有無とメディアタイプを見て、Redocly では 2 本の規則に分けて、それぞれの文で報告させています。$ref で指した 500 は、Spectral も components.responses.InternalError の位置で報告しました。一方、Redocly の規則は OpenAPI のノード型を名前で指すので、JSONPath で仕様の形を書き写さずに済みます。

Redocly CLISpectral
規則の書き方ノード型 (subject) と assertionJSONPath (given) と関数 (then)
試した版2.72.16.17.0
直近の版の公開2.71.0 から 2.72.1 までの 5 つが 2026-10-23 から 10-296.16.1 から 6.17.0 までの 4 つが 2026-06-30 から 10-01
対応する Node.js22.12.0 以上 (20 系なら 20.19.0 以上)22 系か 24 以上
ほかに持つものsplit・bundle・build-docslint に絞った道具

公開の間隔は、Redocly CLI の monorepo の @redocly/cli@ の tag と、Spectral の npm の公開時刻で数えました。どちらも保守は続いています。このガイドは、split・bundle・build-docs を同じ道具でまかなえる Redocly CLI を使います。

vacuum は、Spectral に着想を得た、軽量で速いことを掲げる OpenAPI の linter です。Spectral の ruleset を読めますが、互換には限りがあると README に書かれています (vacuum)。

見直しの観点​

仕様を直す変更の見直しで確かめることです。

  • 規則を足したら、ガイドラインの行と、規則だけに当たる落ちる例を足したか
  • 組み込みの規則を off にしたり重さを変えたりしたら、理由を redocly.yaml かガイドラインに書いたか
  • ガイドラインの「人が見る」の行を、変更に当てたか
  • 新しい操作に、操作ごとの security を書いたか (書き忘れと、最上位への書き足しは lint が落とす)
  • 誤りの応答に default を使っていないか (誤りの応答の 2 つの規則は default に当たらない)
  • 分けたファイルを足したとき、ファイル名に URI に書けない文字が無いか

選ばなかった案​

案選ばなかった理由
recommended を土台にして、要る規則だけ error に上げる上げ忘れた規則の warning は終了コード 0 で CI を通る
security: [] を仕様の最上位に書く後で足した操作に security が無くても security-defined が落とさない
servers に localhost とポートを書くno-server-example.com に当たり、仕様が試しの環境に縛られる
paths-kebab-case を error にするカスタムメソッドの形 (/orders/{orderId}:cancel) も落とし、後の周回で比べる前に片方を塞ぐ
用語集から lint の規則を作るスクリプトにする作り直し忘れを止める仕組みが別に要る。手で写し、テストで照らす
guidelines.md で 08〜10 章の文書を置き換えるテストが読む表の正本が 2 つになるか、テストの読み先をすべて替えることになる
テストが dist/ の束ねた出力を読む束ね直し忘れたときに、テストが古い仕様を確かめて通る
Spectral の ruleset もリポジトリに置く同じ決まりを 2 つの道具で書くと、片方の直し忘れが起きる

実務で効く注意点​

組み込みの規則が見る範囲は、落ちる例で確かめる​

規則の名前と文書から想像する範囲と、実際に当たる範囲は違うことがあります。operation-4xx-problem-details-rfc7807 は 4xx だけを見ますし、security-defined は最上位に security があると操作ごとには見ません。頼る規則は、反した仕様を作って落ちることを 1 度見てから、ガイドラインの守り方に書きます。

lint が通っても、要件に合うとは限らない​

lint が見るのは書き方です。単価を注文した時点の価格から写すこと、在庫が足りないと断ることは、どの規則も見ません。要件との対応は、04 章の受け入れ条件と、後の部のテストで確かめます。

まとめ​

  • 仕様を Redocly CLI で lint し、最初の指摘 (servers と security) は仕様を直して片づけた。security は操作ごとに書き、後で足した操作も見張れるようにした
  • 土台は recommended-strict にした。warning は終了コード 0 で CI を止めないため
  • 08〜10 章の決まりのうち、書き方で判定できるもの (キーと operationId の camelCase・201 の Location・誤りの応答の本文) と、この章で決めた書き方 (最上位の security・スキーマの example・用語集の語・範囲のキーの大文字) を自前の規則にした
  • 規則が見る場所ごとに落ちる例を置き、規則がその例だけで落ちることをテストで確かめた
  • 規約と守り方を guidelines.md にまとめ、型の正本を仕様のスキーマに決めた
  • 仕様を split で分け、bundle で束ねた出力は dist/ に作ってリポジトリに置かない
  • build-docs で Redoc の文書を作り、npm run verify と CI に lint を足した

次に読む​

練習問題​

1. 後の周回で、注文を取り消す操作を足すことになりました。取り消しを POST /orders/{orderId}:cancel (カスタムメソッド) にするか、DELETE や状態の更新で表すかは、まだ決めていません。この章の lint の設定とガイドラインのうち、どれがこの比べに関わり、比べる前に何を決めておく必要がありますか。

解答例

関わるのは、ガイドラインの「標準のメソッドで表せる操作では、パスに動詞を入れない」(人が見る) と、使っていない paths-kebab-case です。paths-kebab-case を error にすると、カスタムメソッドの形は比べる前に lint で落ちます。この章は off のままにしたので、比べた結果カスタムメソッドを選ぶなら、その形を許す決まりをガイドラインに足し (どの操作をカスタムメソッドにしてよいか)、パスの形を確かめる規則を自前で書くかを決めます。標準のメソッドで表すなら、取り消しをどの標準メソッドに当てるかを決め、ガイドラインの「人が見る」の行で見直します。どちらでも、新しい操作には操作ごとの security が要り、security-defined が書き忘れを落とします。

2. 用語集に、使わない語を 1 つ足すことになりました。この章の仕組みでは、どのファイルを直し、直し忘れるとどのテストがどう落ちますか。仕組みをこの形にした理由と、代わりの形の弱みも説明してください。

解答例

直すのは docs/glossary.yaml の avoid と、redocly.yaml の rule/glossary-avoid の正規表現です。足した語を含む用語集の語や allowed の語があれば、正規表現の後読みか先読みにも足します。正規表現を直し忘れると、test/glossary.test.ts の「仕様の lint の規則が、用語集の使わない語にどれも当たり…」が、足した語が当たらないとして落ちます。外す語を足し忘れると、同じテストが、外すはずの語が当たるとして落ちます。正規表現を直すと、lint の指摘の文に正規表現が丸ごと出るので、記事に載せた出力の照合 (test/snippets/ch12-03-lint-glossary-avoid.out) も落ちます。差分を見てから .out を書き出し直します。用語集から正規表現を作るスクリプトにすれば写す手間は無くなりますが、スクリプトを回し忘れたことを止める仕組みが別に要り、記事の例にすればテストの回す順で照合が揺れます。手で写してテストで照らす形は、写す手間と引き換えに、2 つの食い違いをテストで止めます。avoid の語が正規表現から漏れることと、外す語に当たることです。逆向き (用語集から外した語が正規表現に残ること) はテストでは止まらないので、見直しで見ます。

この章のテストのコード​

落ちる例を規則と結び、1 ファイルずつ lint を回す処理です。

/*
* lint の落ちる例 (test/fixtures/lint/) を規則の名前と結び、Redocly CLI の lint を 1 ファイルずつ回す処理。
* 落ちる例は、当たる規則の名前の / を - にしたディレクトリに、変えた所の名前の YAML のファイルで置く
* (rule/created-has-location → rule-created-has-location/no-headers.yaml)。規則が見る場所と、規則の assertion ごとに 1 つ置く。
*/
import { readdirSync } from 'node:fs';
import type { Dirent } from 'node:fs';
import { join } from 'node:path';
import { repoRoot, runRedocly } from './redocly.ts';

/** 落ちる例の置き場。Redocly CLI はリポジトリの root で回すので、root からの相対パスで持つ。 */
export const fixtureDir = 'test/fixtures/lint';

/** どの規則にも当たらない土台。落ちる例は、これの 1 か所 (1 つの応答・スキーマ・値) だけを変えたもの。 */
export const baseFixture = 'valid.yaml';

/** ドットで始まる名前 (エディタや OS が置く隠しファイル。`._no-headers.yaml`・`.#no-headers.yaml` など) は、拡張子が YAML でも読まない。 */
function visible(dir: string): Dirent[] {
return readdirSync(dir, { withFileTypes: true }).filter((entry) => !entry.name.startsWith('.'));
}

/**
* 落ちる例 (fixtureDir からのパス) と、それが当たるはずの規則の名前。
* 読まないもの (規則のディレクトリの外のファイル・YAML でないファイル・規則のディレクトリの下のディレクトリ) があれば例外にする。
* どの規則とも結ばれないまま、回されずに通るため。
*/
export function lintFixtures(root = join(repoRoot, fixtureDir)): { file: string; rule: string }[] {
const entries = visible(root);
const stray = entries.filter((entry) => !entry.isDirectory() && entry.name !== baseFixture).map((entry) => entry.name);
if (stray.length > 0) throw new Error(`規則のディレクトリの外にファイルがある: ${stray.join(', ')}`);
return entries
.filter((entry) => entry.isDirectory())
.map((entry) => entry.name)
.sort()
.flatMap((dir) => {
const rule = dir.startsWith('rule-') ? `rule/${dir.slice('rule-'.length)}` : dir;
const files = visible(join(root, dir));
const unread = files.filter((entry) => !entry.isFile() || !/\.ya?ml$/.test(entry.name)).map((entry) => `${dir}/${entry.name}`);
if (unread.length > 0) throw new Error(`落ちる例として読まないものがある (YAML のファイルだけを置く): ${unread.join(', ')}`);
return files
.map((entry) => entry.name)
.sort()
.map((file) => ({ file: `${dir}/${file}`, rule }));
});
}

/**
* 1 つのファイルを redocly.yaml の規則で lint し、終了コードと、指摘のあった規則の名前 (重ねない) を返す。
* 複数のファイルを 1 回で渡すと JSON の文書がファイルの数だけ続いて出るので、1 ファイルずつ回す。
*/
export function lintFile(path: string): { status: number | null; rules: string[] } {
const result = runRedocly(['lint', path, '--format=json', '--lint-config=error']);
let report: { problems: { ruleId: string }[] };
try {
report = JSON.parse(result.stdout) as { problems: { ruleId: string }[] };
} catch {
// 設定の誤りでは JSON を出さず、理由を stderr に書いて止まるので、理由を失敗の文に載せる。
throw new Error(`${path} の lint の出力が JSON でない (終了コード ${result.status})。stderr:\n${result.stderr}`);
}
return { status: result.status, rules: [...new Set(report.problems.map((problem) => problem.ruleId))].sort() };
}

規則が落ちる例でだけ落ちることを確かめるテストです。

/*
* redocly.yaml の規則が、規則ごとに作った落ちる例でその規則だけを報告し、土台の仕様には何も報告しないことを確かめる。
* 規則の書き方を誤っても (where の祖先の型・どこにも当たらない親のキーの絞り・狭い正規表現)、設定として正しい形なら
* --lint-config=error でも止まらず、その規則は当たるべき場所に当たらないまま lint が通るので、
* 仕様の lint が通ることだけでは、規則が働いている証にならないため。
*/
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { describe, expect, it } from 'vitest';
import { parse } from 'yaml';
import { baseFixture, fixtureDir, lintFile, lintFixtures } from './support/lint.ts';

const fixtures = lintFixtures();

describe('落ちる例の読み方', () => {
/** 一時のディレクトリに files (パスと中身) を置いて、lintFixtures で読む。 */
function listed(files: string[]): () => { file: string; rule: string }[] {
const root = mkdtempSync(join(tmpdir(), 'lint-fixtures-'));
for (const file of files) {
mkdirSync(join(root, file, '..'), { recursive: true });
if (!file.endsWith('/')) writeFileSync(join(root, file), '');
}
return () => {
try {
return lintFixtures(root);
} finally {
rmSync(root, { recursive: true, force: true });
}
};
}

it('規則のディレクトリの YAML のファイルを規則と結び、ドットで始まる名前は読まない', () => {
const read = listed([baseFixture, '.DS_Store', 'rule-a/x.yaml', 'rule-a/._x.yaml', 'rule-a/.#x.yaml', 'b/y.yml']);
expect(read()).toEqual([
{ file: 'b/y.yml', rule: 'b' },
{ file: 'rule-a/x.yaml', rule: 'rule/a' },
]);
});

it('規則のディレクトリの外のファイル・YAML でないファイル・規則のディレクトリの下のディレクトリは、例外にする', () => {
expect(listed([baseFixture, 'stray.yaml'])).toThrow('規則のディレクトリの外にファイルがある: stray.yaml');
expect(listed([baseFixture, 'rule-a/x.json'])).toThrow('rule-a/x.json');
expect(listed([baseFixture, 'rule-a/sub/x.yaml'])).toThrow('rule-a/sub');
});
});

it('土台の仕様は、どの規則にも当たらない', () => {
expect(lintFile(`${fixtureDir}/${baseFixture}`)).toEqual({ status: 0, rules: [] });
});

it.each(fixtures)('落ちる例 $file は、$rule だけに当たって lint が落ちる', ({ file, rule }) => {
expect(lintFile(`${fixtureDir}/${file}`)).toEqual({ status: 1, rules: [rule] });
});

it('redocly.yaml の自前の規則には、どれも落ちる例がある', () => {
const config = parse(readFileSync(new URL('../redocly.yaml', import.meta.url), 'utf8')) as { rules?: Record<string, unknown> };
const custom = Object.keys(config.rules ?? {}).filter((name) => name.startsWith('rule/')).sort();
expect(custom.length).toBeGreaterThan(0);
expect(custom.filter((name) => !fixtures.some((fixture) => fixture.rule === name))).toEqual([]);
});

ガイドラインの守り方の列を確かめるテストです。

/*
* API の設計のガイドライン (docs/api-design/guidelines.md) の守り方の列が、実際に働く守りを指していることを確かめる。
* 規則やテストの名前を変えたり消したりしても、ガイドラインの表は文書なので古いまま残り、守っていない規約を守っていると読めるため。
*/
import { existsSync, readFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import ts from 'typescript';
import { expect, it } from 'vitest';
import { lintFixtures } from './support/lint.ts';

function read(path: string): string {
return readFileSync(fileURLToPath(new URL(`../${path}`, import.meta.url)), 'utf8');
}

const header = '| 規約 | 決めた文書 | 守り方 |';

/** ガイドラインの表の守り方の列。表の見出しの次の区切りの行から空行の前までの行の、最後の列を返す。 */
function protectionCells(text: string): string[] {
const lines = text.split(/\r?\n/);
const cells: string[] = [];
lines.forEach((line, index) => {
if (line !== header) return;
for (const row of lines.slice(index + 2)) {
if (row.trim() === '') break;
const columns = row.split(' | ');
cells.push(columns[columns.length - 1].replace(/ \|$/, ''));
}
});
return cells;
}

/**
* 守り方の 1 つずつの形。どれにも合わない書き方は誤りにする
* (綴りを崩した守り方が、照らされないまま守っていると読めるため)。
*/
const lintPattern = /^lint: `([^`]+)`$/;
const testPattern = /^テスト: `([^`]+)` の「([^」]+)」$/;

const cells = protectionCells(read('docs/api-design/guidelines.md'));
const parts = cells.flatMap((cell) => cell.split(' / '));

/** describe.skip・describe.todo・it.skip・it.todo の呼び出し。止めたテストで守っていないので、中の it を数えない。 */
function isStopped(node: ts.Node): boolean {
return (
ts.isCallExpression(node) &&
ts.isPropertyAccessExpression(node.expression) &&
ts.isIdentifier(node.expression.expression) &&
['describe', 'it'].includes(node.expression.expression.text) &&
['skip', 'todo'].includes(node.expression.name.text)
);
}

/**
* ファイルの中の it('<名前>', …) の呼び出しの名前。ファイルを文字として探すと、コメントや文字列の中の it と、
* describe.skip の中の it でも見つかるので、構文木で呼び出しだけを拾い、止めたスコープの中は数えない。
*/
function itNames(path: string): string[] {
const source = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest);
const names: string[] = [];
const visit = (node: ts.Node): void => {
if (isStopped(node)) return;
if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'it') {
const [first] = node.arguments;
if (first !== undefined && (ts.isStringLiteral(first) || ts.isNoSubstitutionTemplateLiteral(first))) names.push(first.text);
}
ts.forEachChild(node, visit);
};
visit(source);
return names;
}

it('ガイドラインの守り方は、どれも lint・テスト・人が見るの形で書かれている', () => {
expect(cells.length).toBeGreaterThan(0);
expect(parts.filter((part) => !lintPattern.test(part) && !testPattern.test(part) && part !== '人が見る')).toEqual([]);
});

it('ガイドラインの lint の規則と、落ちる例を置いた規則が 1 対 1', () => {
const named = parts.flatMap((part) => lintPattern.exec(part)?.[1] ?? []).sort();
expect(named.length).toBeGreaterThan(0);
expect(new Set(named).size, 'ガイドラインで同じ規則を 2 度挙げていない').toBe(named.length);
expect(named).toEqual([...new Set(lintFixtures().map((fixture) => fixture.rule))].sort());
});

it('ガイドラインのテストは、そのファイルに同じ名前の it がある', () => {
const tests = parts.flatMap((part) => {
const match = testPattern.exec(part);
return match === null ? [] : [{ file: match[1], name: match[2] }];
});
expect(tests.length).toBeGreaterThan(0);
const missing = tests.filter(({ file, name }) => {
const path = fileURLToPath(new URL(`../${file}`, import.meta.url));
return !existsSync(path) || !itNames(path).includes(name);
});
expect(missing).toEqual([]);
});

用語集のテストに足した、lint の規則と用語集を照らす部分です。

/**
* 仕様の lint の規則 rule/glossary-avoid が探す正規表現 (redocly.yaml に、用語集から手で写したもの)。
* Redocly は notPattern の '/<式>/<フラグ>' を正規表現として読むので、同じ形で JavaScript の正規表現にする。
*/
function lintPattern(): RegExp | undefined {
const config: unknown = parse(readFileSync(join(root, 'redocly.yaml'), 'utf8'));
const rule = isRecord(config) && isRecord(config.rules) ? config.rules['rule/glossary-avoid'] : undefined;
const notPattern = isRecord(rule) && isRecord(rule.assertions) ? rule.assertions.notPattern : undefined;
const match = typeof notPattern === 'string' ? /^\/(.+)\/([a-z]*)$/s.exec(notPattern) : null;
return match === null ? undefined : new RegExp(match[1], match[2]);
}

it('仕様の lint の規則が、用語集の使わない語にどれも当たり、その語を含む用語集の語と allowed の語には当たらない', () => {
expect(problems).toEqual([]);
const pattern = lintPattern();
expect(pattern, 'redocly.yaml の rule/glossary-avoid の notPattern').toBeDefined();
const words = glossary.terms.flatMap((term) => term.avoid ?? []);
expect(words.length).toBeGreaterThan(0);
expect(words.filter((word) => !pattern?.test(word))).toEqual([]);
// 05 章の確かめと同じく、使わない語を含む用語集の語と allowed の語 (消費税額など) は、その語として探さない。
const containing = [...names, ...(glossary.allowed ?? [])].filter((other) => words.some((word) => other !== word && other.includes(word)));
expect(containing.length).toBeGreaterThan(0);
expect(containing.filter((other) => pattern?.test(other))).toEqual([]);
});

テストが仕様を読む処理は、分けた仕様をその場で束ねるように変えました。テストのコードは、束ねる入口のパスを specEntry の名前で引きます。

/**
* 仕様の入口 (リポジトリの root からの相対パス)。テストはこの名前で引く。package.json の lint と bundle の script も
* 同じパスを書く。JSON の script はこの名前を引けないので、入口を変えたらその 2 つも直す。
*/
export const specEntry = 'openapi/openapi.yaml';

/**
* 分けた仕様を一時のファイルに束ね、内部の参照 ('#/components/...') だけを持つ 1 つの文書にして返す。
* npm run bundle が作る dist/ は読まない。元を直して束ね直し忘れると、テストが古い仕様を確かめて通るため。
*/
export function loadSpec(): unknown {
const dir = mkdtempSync(join(tmpdir(), 'rest-api-order-spec-'));
try {
const out = join(dir, 'openapi.yaml');
const result = runRedocly(['bundle', specEntry, '--output', out]);
if (result.status !== 0) throw new Error(`仕様を束ねられない:\n${result.stderr}`);
return parse(readFileSync(out, 'utf8'));
} finally {
rmSync(dir, { recursive: true, force: true });
}
}