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

「openapi」タグのついた4記事

全てのタグを見る

OpenAPI: 3.1 で仕様を書いて Swagger UI で読む

REST API 設計・実装ガイドの第11章。08〜10 章で決めたエンドポイント・表現・誤りの応答を、OpenAPI 3.1 の仕様に書きます。文書の構造、操作と operationId、パラメータとリクエストの本文、JSON Schema 2020-12 のスキーマ、$ref と components、例と問題の詳細の書き方を、選んだ理由と一緒に示します。仕様が設計の文書と食い違わないことをテストで確かめ、書いた仕様を Swagger UI で読みます。

REST API 設計・実装ガイド

REST API の設計と実装を、EC サイトの注文 API を題材に、要件の整理から OpenAPI の仕様・モック・TypeScript の実装・PostgreSQL・運用まで通して学ぶ全 50 章のガイド。Swagger UI・Redocly CLI・Prism・Bruno などの道具の使い方も扱います。対象は OpenAPI 3.1・Node.js 26・TypeScript 6.0 です。

モック: Prism で動かして curl と Bruno で呼ぶ

REST API 設計・実装ガイドの第13章。束ねた OpenAPI の仕様から Prism でモックを動かし、curl で呼びます。Prefer ヘッダで応答を選ぶ方法、Prism のリクエストの検証と誤りの応答がエラーの設計の章の決まりとどう違うか、値を作る形のモックを示します。受け入れ条件を Bruno のリクエストにしてモックで確かめ、モックで確かめられない受け入れ条件を表にします。Swagger UI の Try it out からモックを呼ぶための CORS と、Postman との比べ方も扱います。

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

REST API 設計・実装ガイドの第12章。11 章で書いた OpenAPI の仕様を Redocly CLI で検査します。組み込みの規則集の選び方、指摘への応じ方、08〜10 章の決まりを自前の規則にする書き方、規則が働くことをテストで確かめる形、規約ごとに守り方を書くガイドラインを示します。仕様をファイルに分けて束ね、Redoc の文書を作り、検査を npm run verify と CI に足します。