投稿日
サービス開発リファレンスの方式設計ガイドを使ってみよう
もくじ
- はじめに
- 事前準備
- ファイル・ディレクトリ構成の説明
- .gitlab ディレクトリ
- docs ディレクトリ
- overrides ディレクトリ
- .gitignore ファイル
- .gitlab-ci.yml ファイル
- .textlintrc ファイル
- CHANGELOG.md ファイル
- mkdocs.yml ファイル
- package-lock.json 、 package.json ファイル
- prh.yml ファイル
- README.md ファイル
- 不要なファイルの削除
- 変更履歴の削除
- GitLabを使用しない場合
- 文章構成を使用しない場合
- ドキュメントをローカル環境で表示する
- タイトルを修正する
- トップページの説明を修正する
- 新しいページを追加する
- 文章を校正する
- 変更後のドキュメントを確認する
- デプロイ用のドキュメントを生成する
- まとめ
はじめに
こんにちは。西日本テクノロジー&イノベーション室の樋尻です。
私の所属する西日本テクノロジー&イノベーション室では、2020年9月末に「SPA + REST API構成のサービス開発リファレンス(以下サービス開発リファレンス)」を公開しました。こちらは、シングルページアプリケーション(以下SPA)とREST APIから構成されるWebアプリケーションを開発する際に活用して頂けるコンテンツになっています。
前回のブログでは、CSRF対策をするための実装をご紹介しました。
今回は、コンテンツのひとつである「方式設計ガイド」をベースに、方式設計書を作成する方法をご紹介します。
この方式設計ガイドには、SPAとREST APIで構成されるWebアプリケーションの開発でよくある基本的な方式設計が記述されています。これをベースにして、プロジェクト固有の方式設計を付け加えたり一部を編集したりすることで、方式設計書を容易に作成できます。
方式設計ガイドはMkDocsを使用してドキュメントを生成しています。本文についてはMarkdown形式で記述しているため様々なツールで扱いやすく、生成したドキュメントをサーバにデプロイすることでブラウザから参照したりもできますので、それらの例についてもご紹介します。
- サービス開発リファレンスを使ってWebアプリケーションを作成してみよう<導入編>
- サービス開発リファレンスを使って1画面作成してみよう
- サービス開発リファレンスを使ってREST APIを1つ作成してみよう
- サービス開発リファレンスを使ってバリデーションしてみよう
- サービス開発リファレンスを使ってファイルダウンロードを実装してみよう
- サービス開発リファレンスを使ってCSRF対策を実装してみよう
- サービス開発リファレンスの方式設計ガイドを使ってみよう(←今回の記事)
事前準備
方式設計ガイドのソースコードは、GitHubのspa-restapi-guideリポジトリで公開されています。こちらをClone、またはZipでダウンロードして、手元に用意します。
READMEに必要なソフトウェアが記載されていますので、これらを使用できるように準備します。ここでは Docker
を使用する方法で進めていきます。
ファイル・ディレクトリ構成の説明
方式設計ガイドは、MkDocsを使用してドキュメントを生成しています。そのため、リポジトリではMkDocsでドキュメントを生成するために必要なファイルや設定が格納されています。
リポジトリ内のファイルおよびディレクトリ構成は次のとおりです。
spa-restapi-guide
├── .gitlab/
│ └── GitLab用の設定ファイル群
├── docs/
│ └── 方式設計ガイドの文章を定義したファイル群
├── overrides/
│ └── 共通の出力設定ファイル群
├── .gitignore
├── .gitlab-ci.yml
├── .textlintrc
├── CHANGELOG.md
├── mkdocs.yml
├── package-lock.json
├── package.json
├── prh.yml
└── README.md
.gitlab
ディレクトリ
GitLabでリポジトリとして管理する際の設定ファイルが格納されています。
docs
ディレクトリ
MkDocsのドキュメントに出力される内容を、Markdown形式で定義しているファイルが格納されています。
このディレクトリ内を変更することで、方式設計ガイドの内容をカスタマイズしていきます。
overrides
ディレクトリ
MkDocsのドキュメント生成で共通的に使用する設定ファイルが格納されています。
.gitignore
ファイル
Git管理対象外を定義したファイルです。
.gitlab-ci.yml
ファイル
GitLab CIの設定ファイルです。MkDocsのドキュメント生成を実行するためのビルド設定を定義しています。
.textlintrc
ファイル
文章構成ツールの textlint
で使用する設定ファイルです。
CHANGELOG.md
ファイル
変更履歴を記載したファイルです。
mkdocs.yml
ファイル
MkDocsの設定ファイルです。
package-lock.json
、 package.json
ファイル
npmの設定ファイルです。 textlint
を実行するための設定をしています。
prh.yml
ファイル
文章構成ツールの textlint
で使用する設定ファイルです。
README.md
ファイル
リポジトリの説明を記載したファイルです。
不要なファイルの削除
変更履歴の削除
方式設計ガイドの変更履歴が記載されていますので、次のファイルを削除、または内容を変更してください。
CHANGELOG.md
ファイル
GitLabを使用しない場合
GitLabでリポジトリ管理しない場合は、次のファイルおよびディレクトリを削除してください。
.gitlab
ディレクトリ.gitlab-ci.yml
ファイル
文章構成を使用しない場合
文章構成を使用しない場合は、次のファイルおよびディレクトリを削除してください。
.textlintrc
ファイルpackage-lock.json
ファイルpackage.json
ファイルprh.yml
ファイル
ドキュメントをローカル環境で表示する
まず、ローカル環境でドキュメントを表示できるか確認します。
最初に説明しましたとおり、今回は MkDocks
の各コマンドを実行する方法として Docker
を使用します。次のコマンドで MkDocs
のサーバ起動コマンドを実行します。
docker run -it --rm -p 8000:8000 -v %cd%:/docs squidfunk/mkdocs-material@sha256:c1e9396754016164fc360444cc6629e7dd7ad0423a9e76218abc521d7d800397 serve -a 0.0.0.0:8000
(Windowsのコマンドプロンプト以外で実行される場合には %cd%
の部分を $(pwd)
に読み替えてください)
コマンドが実行されると、ドキュメントを表示するためのサーバが起動します。
ブラウザで localhost:8000 にアクセスすることで、ドキュメントを表示できます。アクセスすると、次のページが表示されます。
確認できたら、 Ctrl + C
で起動したサーバを終了します。
なお、ここで実行したコマンドの説明は README.md
にも記載されています。
タイトルを修正する
mkdocs.yml
ファイル内の site_name
がタイトルになるため、これを修正します。ここでは「タスク管理プロジェクトの方式設計書」に変更します。
site_name: タスク管理プロジェクトの方式設計書
nav:
- index.md
- validation.md
- api-design.md
- fetch.md
- cors.md
- download.md
- upload.md
- xss.md
- csrf.md
theme:
name: material
language: 'ja'
custom_dir: overrides
markdown_extensions:
- admonition
- codehilite
トップページの説明を修正する
トップページの内容は docs/index.md
ファイルに定義しているため、これを修正します。ここでは次の内容に変更します。
# 本ドキュメントについて
本ドキュメントは、タスク管理プロジェクトの方式設計書です。
新しいページを追加する
プロジェクト固有の方式設計を付け加える例として、ここでは認証に関するドキュメントを追加してみます。
認証を説明するページとして docs
ディレクトリ内に authentication.md
ファイルを新しく作成します。
ファイルは次の内容にします。
# 認証
本アプリケーションでは、アカウントを識別するため、メールアドレスおよびパスワードを用いたフォーム認証を使用する。
各アカウントのパスワードは、パスワードの漏洩を防止するため、不可逆暗号化(ハッシュ化)した状態でデータベース上に保存する。
次に、この認証ページを目次に追加します。目次は mkdocs.yml
ファイル内の nav
で定義できますので、 nav
の最後に先ほど作成した authentication.md
を追加します。
site_name: タスク管理プロジェクトの方式設計書
nav:
- index.md
- validation.md
- api-design.md
- fetch.md
- cors.md
- download.md
- upload.md
- xss.md
- csrf.md
- authentication.md
theme:
name: material
language: 'ja'
custom_dir: overrides
markdown_extensions:
- admonition
- codehilite
文章を校正する
文章を校正するための textlint
がnpmで設定されていますので、これを使用してみます。
まず次のコマンドを実行して、必要なモジュールを取得します。
$ npm install
完了しましたら、 次は package.json
に定義された test
スクリプトで textlint
を実行します。
$ npm test
すると、次のようなエラーが出力されます。
(省略)/docs/authentication.md
5:31 error 漢字が6つ以上連続しています: 不可逆暗号化 ja-technical-writing/max-kanji-continuous-len
✖ 1 problem (1 error, 0 warnings)
npm ERR! Test failed. See above for more details.
このエラーを解消するため、authentication.md
を次の内容に変更します。
# 認証
本アプリケーションでは、アカウントを識別するため、メールアドレスおよびパスワードを用いたフォーム認証を使用する。
各アカウントのパスワードは、パスワードの漏洩を防止するため、ハッシュ化した状態でデータベース上に保存する。
もう一度 npm test
を実行し、エラーが出力されないことを確認します。
なお、 textlint
の設定は .textlintrc
ファイルと prh.yml
ファイルで変更できます。 textlintのドキュメントを参考に、必要に応じて変更してください。
変更後のドキュメントを確認する
ここまでで変更した内容で、ドキュメントを生成して表示してみます。
変更前に表示した手順と同じく、次のコマンドで MkDocs
のサーバ起動コマンドを実行します。
docker run -it --rm -p 8000:8000 -v %cd%:/docs squidfunk/mkdocs-material@sha256:c1e9396754016164fc360444cc6629e7dd7ad0423a9e76218abc521d7d800397 serve -a 0.0.0.0:8000
※
サーバが起動したら、ブラウザで localhost:8000 にアクセスします。
変更した内容が反映されていることを確認します。
確認できたら、 Ctrl + C
で起動したサーバを終了します。
デプロイ用のドキュメントを生成する
ドキュメントを表示した時と同じく Docker
を使用します。次のコマンドで MkDocs
のドキュメント生成コマンドを実行します。
docker run --rm -v %cd%:/docs squidfunk/mkdocs-material@sha256:c1e9396754016164fc360444cc6629e7dd7ad0423a9e76218abc521d7d800397 build
コマンドが慣用すると、site/
ディレクトリが作成され、その中にデプロイするためのファイル群が生成されています。先ほどローカル環境で表示した内容と同じ内容になっていますので、これらをWebサーバ等にデプロイすることで、任意の環境で表示できます。
なお、ここで実行したコマンドの説明は README.md
にも記載されています。
公開方法の一例として、最初に配置されている .gitlab-ci.yml
ファイルでは、GitLab CIでドキュメントを生成してGitLab Pagesで公開するような設定になっています。GitLab Pagesでは public
という名前で成果物配置する必要があるため、 site
が生成されたらディレクトリ名を変更しています。
まとめ
今回は、サービス開発リファレンスの方式設計ガイドをベースにして、方式設計書を作成しました。 次回はバックエンドのみサービス開発リファレンスを使用するケースについてご紹介します。
本コンテンツはクリエイティブコモンズ(Creative Commons) 4.0 の「表示—継承」に準拠しています。