私たちは皆、SwaggerUI が大好きです。Swagger/OpenAPI が非常に人気がある理由の 1 つです。最近、API ドキュメントの世界でいくつかの新しいトレンドが現れました。その 1 つが、3 パネルデザインのドキュメントです。競合する API 仕様形式には、たとえば API Blueprint には aglio があり、Postman には Postman Documenter などがあります。
そのため、APIs.guru は、OpenAPI を活用した新しいドキュメント、ReDoc を開発してきました。これはクライアントである Rebilly のために開発しましたが、完全にオープンソースで無料です！
デモをチェックしてください！
3 パネルデザイン
ReDoc はレスポンシブな 3 パネルデザインで作成されています
左パネルにはスクロールと同期したリファレンスメニューが含まれています。中央パネルにはエンドポイント/メソッドのドキュメントが含まれています。右パネルには、リクエストサンプル、レスポンスサンプル、コードサンプル（ベンダー拡張機能経由）など、さまざまなサンプルが含まれています。
ペイロードのドキュメント
ReDoc の主な機能は、複雑なリクエスト/レスポンスペイロードをドキュメント化する機能です
ご覧のとおり、ReDoc はネストされたスキーマをサポートし、それらをその場で折りたたみ/展開できる機能とともに表示します。
また、信じられないかもしれませんが、ReDoc は discriminator: をサポートしています。
レスポンスのドキュメント
すべてのメソッドのレスポンスは、メソッド定義の下にリストされ、レスポンスコードに従って色分けされています。レスポンスには、ヘッダーとペイロードのドキュメントも含まれています
サンプル
ペイロードサンプルは JSON スキーマに基づいて生成されます。私たちは、意味のあるサンプルを生成する OpenAPI-sampler ツールを開発しました。type と format に加えて、仕様の default、enum、example フィールドを利用しています。
サンプルは大きくなる可能性があるため、デフォルトでは最初のレベルのみが展開されます。「コピー」ボタンを使用して、完全なサンプルをクリップボードにコピーすることもできます。
前述のとおり、ReDoc は OpenAPI ベンダー拡張機能を通じてカスタムコードサンプルをサポートしています。詳細については、ドキュメント または サンプルスキーマ を参照してください。
その他の機能
簡単な統合
バックエンドは不要です。すべての ReDoc リソース（HTML、CSS、JS）は単一のファイルにバンドルされており、当社の CDN からアクセスできます。最小限の index.html を参照してください
<!DOCTYPE html>
<html>
<head>
<title>API ドキュメント</title>
<!-- モバイルデバイスに必要 -->
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
<script src="https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js"></script>
</body>
</html>
はじめにセクション
ReDoc は Swagger の説明から 1 レベルの Markdown 見出しを抽出し、それらをリファレンスメニューに表示します！これにより、API ドキュメントにカスタムセクションを簡単に追加できます。
ブランドロゴ
ReDoc は x-logo ベンダー拡張機能を使用して、ドキュメントにブランドロゴを表示します。
次は何ですか？
すでに新しいリリースに向けて作業を開始しています。どのような新機能が追加されるかは、皆様からのフィードバック次第です！GitHub で問題や機能リクエストを遠慮なく開いてください。皆様のご提案をお待ちしております！
また、ReDoc の統合を支援したり、ReDoc を活用したドキュメントに独自のルックアンドフィールを開発するために APIs.guru を雇うこともできます。
GitHub でプロジェクトにスターを付けるのを忘れないでください！<3