OpenAPI 仕様で書かれた API ドキュメントをWebページとしてみる
こんにちは、 @kz_morita です。
普段、openapi 形式の yaml ファイルで API 仕様書を管理していますが、それを見やすい形にドキュメントする方法について書きます。
普段は、openapi 仕様形式の yaml を Stoplight Studio を使って編集しています。 その yaml ファイルから generator を使って、API が返すモデルを自動生成しています。
Stoplight Studio でも見れますが、編集用ということもあり若干見にくいのとどこかのサーバーにホスティングできないかと調べたところ方法があったのでメモです。
HTML でAPI ドキュメントを表示する 結論からいうと、以下のような HTML を書くと API ドキュメントを Web ページとして見ることができます。
<html lang="ja"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" /> <title>API Docs</title> <script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script> <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css" /> </head> <body> <elements-api apiDescriptionUrl="openapi.yml" router="hash" /> </body> </html> 詳しくはこちらの 公式ドキュメント にも記載があります。
HTML ファイルなのであとは、S3 や GitHub Pages など何らかの方法でホスティングすることで API ドキュメントを見ることができるようになります。 公式のドキュメントを見る限り、React や GatsbyJS、Angular なども対応しているそうです。
blog.foresta.me