背景
Swagger超初心者かつQiita初投稿です。
SwaggerでAPIドキュメントを書いてGithub Pagesで簡単に講師する方法をまとめます。
サーバーをもたないでとりあえず仕様書を見せれるようにしたいときにどうぞ。
（Swagger初心者で同じように困っている人に役立てれば…!）
下記のgithubに書かれていた内容を少し変更してやってみた感じです
https://github.com/peter-evans/swagger-github-pages
操作
0.準備
Github Pagesで最終的に公開するためのdocsディレクトリと、とりあえずサンプルで公開したいswagger.yamlを用意します。
.
└── docs
└── swagger.yaml
swagger: '2.0'
info:
version: 1.0.0
title: タイトル
paths:
'/user/{id}':
get:
description: ユーザー情報取得
parameters:
- name: id
in: path
description: user id
required: true
type: number
responses:
'200':
description: 成功
schema:
type: object
properties:
id:
type: integer
username:
type: string
1. Swagger UIのソースコードを取得
Swagger UIのGithubからソースコードを取得します。
今回は手っ取り早くZIPでダウンロードします。
https://github.com/swagger-api/swagger-ui/archive/master.zip
2. distディレクトリをdocsに追加
distディレクトリのみ使用するのでZIPファイルから解凍して、docs以下に配置します。
$ mkdir docs/dist
$ unzip -d docs/dist -j ~/Downloads/swagger-ui-master.zip */dist/*
-
~/Downloads/swagger-ui-master.zipは1で取得したZIPファイル
3. index.htmlの修正
docs/dist/index.htmlのSwaggerファイルのパスを修正して、用意したSwaggerファイルへ変更します。
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
- url: "https://petstore.swagger.io/v2/swagger.json",
+ url: "../swagger.yaml", // my swagger file
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
4. githubへpush
これでファイルの準備は完了したので、ファイルをすべてコミットしてgithubへpushします。
.
└── docs
├── dist
│ ├── favicon-16x16.png
│ ├── favicon-32x32.png
│ ├── index.html
│ ├── oauth2-redirect.html
│ ├── swagger-ui-bundle.js
│ ├── swagger-ui-bundle.js.map
│ ├── swagger-ui-standalone-preset.js
│ ├── swagger-ui-standalone-preset.js.map
│ ├── swagger-ui.css
│ ├── swagger-ui.css.map
│ ├── swagger-ui.js
│ └── swagger-ui.js.map
└── swagger.yaml
5. Github Pagesの設定
Githubへのpushが完了したら設定をしてGithub Pagesで公開します。
- GithubのSettingsを開く
- 「GitHub Pages」の「Source」を「master branch /docs folder」へ変更(初期値は「None」)
- すぐ横の「Save」で保存
これでGithub Pagesでの公開が完了です。
6. ブラウザでアクセス
これで設定がすべて完了したのでブラウザでアクセスできるようになっています。
ブラウザで下記のURLにアクセスして表示できたら完了です。
https://<username>.github.io/<repository>/dist/index.html
まとめ
これでサーバーとかをもたずに、Swaggerファイルを変更するだけで最新のAPI仕様書が公開できるようになります。
上記の操作したGithubはこちらになります。
- Github
- Github Pages
余談
今のindex.htmlはdistディレクトリの下にあるため、URLにもdistが含まれてしまってます。
省略させたい場合は、index.htmlを修正するとできます。
-
index.htmlを上の階層へ移動する-
docs/dist/index.html=>docs/index.html
-
- Swaggerファイルなどのパスを変更する
@@ -4,9 +4,9 @@
<head>
<meta charset="UTF-8">
<title>Swagger UI</title>
- <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >
- <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
- <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
+ <link rel="stylesheet" type="text/css" href="dist/swagger-ui.css" >
+ <link rel="icon" type="image/png" href="dist/favicon-32x32.png" sizes="32x32" />
+ <link rel="icon" type="image/png" href="dist/favicon-16x16.png" sizes="16x16" />
<style>
html
{
@@ -33,13 +33,13 @@
<body>
<div id="swagger-ui"></div>
- <script src="./swagger-ui-bundle.js"> </script>
- <script src="./swagger-ui-standalone-preset.js"> </script>
+ <script src="dist/swagger-ui-bundle.js"> </script>
+ <script src="dist/swagger-ui-standalone-preset.js"> </script>
<script>
window.onload = function() {
// Begin Swagger UI call region
const ui = SwaggerUIBundle({
- url: "../swagger.yaml", // my swagger file
+ url: "./swagger.yaml", // my swagger file
dom_id: '#swagger-ui',
deepLinking: true,
presets: [