GitHubPagesでSwaggerUIホスティング

Swaggerについて

THE WORLD'S MOST POPULAR API TOOLING
世界で最も人気のあるAPIツール
Swagger is the world’s largest framework of API developer tools for the OpenAPI Specification(OAS), enabling development across the entire API lifecycle, from design and documentation, to test and deployment.
Swaggerは、OpenAPI仕様（OAS）のためのAPI開発ツールの世界最大のフレームワークであり、APIのライフサイクル全体にわたって、設計から文書化、テストおよびデプロイまでを可能にします。
https://swagger.io

特徴

• YAML/JSONでAPI仕様を記述

• AWS ApiGateway等にサポートされておりインポート/エクスポート可能

• 各種ツールが備わっている

  • Swagger Editor : API仕様の編集とバリデーションチェック
  • Swagger Codegen : API仕様を元にコード生成
  • Swagger UI : API仕様を元に可視化
  • Swagger Inspector : テストツール

GitHub Pages

• 新しくサーバを用意する必要がない

• バージョン管理しつつ最新のAPI仕様を表示できる

手順

1. Swagger UIリポジトリ https://github.com/swagger-api/swagger-ui に含まれる /dist ディレクトリをコピー

2. dist/index.html 内のswagger定義の参照先を変更する
   https://github.com/swagger-api/swagger-ui/blob/master/dist/index.html#L77

3. ファイル一式をGitHubにPushする

4. GitHub > Settings > GitHub Pages からGitHub Pagesを有効にする

5. Check https://{user_name}.github.io/{repository_name}/

参考

• 公式手順 https://swagger.io/docs/swagger-tools > Swagger UI Documentation > Usage

• 実装例 https://github.com/gyamoto/swagger-pages-sample

• npmのモジュールも用意されている https://www.npmjs.com/package/swagger-ui-dist

• SwaggerUIのテーマがある http://meostrander.com/swagger-ui-themes