はじめに

こんにちは。西日本テクノロジー＆イノベーション室の樋尻です。

私の所属する西日本テクノロジー＆イノベーション室では、2020年9月末に「SPA + REST API構成のサービス開発リファレンス（以下サービス開発リファレンス）」を公開しました。こちらは、シングルページアプリケーション（以下SPA）とREST APIから構成されるWebアプリケーションを開発する際に活用して頂けるコンテンツになっています。

前回のブログでは、CSRF対策をするための実装をご紹介しました。

今回は、コンテンツのひとつである「方式設計ガイド」をベースに、方式設計書を作成する方法をご紹介します。

この方式設計ガイドには、SPAとREST APIで構成されるWebアプリケーションの開発でよくある基本的な方式設計が記述されています。これをベースにして、プロジェクト固有の方式設計を付け加えたり一部を編集したりすることで、方式設計書を容易に作成できます。

方式設計ガイドはMkDocsを使用してドキュメントを生成しています。本文についてはMarkdown形式で記述しているため様々なツールで扱いやすく、生成したドキュメントをサーバにデプロイすることでブラウザから参照したりもできますので、それらの例についてもご紹介します。

  1. サービス開発リファレンスを使ってWebアプリケーションを作成してみよう＜導入編＞
  2. サービス開発リファレンスを使って1画面作成してみよう
  3. サービス開発リファレンスを使ってREST APIを1つ作成してみよう
  4. サービス開発リファレンスを使ってバリデーションしてみよう
  5. サービス開発リファレンスを使ってファイルダウンロードを実装してみよう
  6. サービス開発リファレンスを使ってCSRF対策を実装してみよう
  7. サービス開発リファレンスの方式設計ガイドを使ってみよう（←今回の記事）

    事前準備

    方式設計ガイドのソースコードは、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 の「表示—継承」に準拠しています。