Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
23
Help us understand the problem. What is going on with this article?
@endk

YAML で画面設計書を書いて Markdown で出力する

More than 1 year has passed since last update.

タイトルの内容をこうやってみましたというレポートです。

経緯

  • 小さめ(画面10未満)・比較的単純なWebアプリ案件の設計書を記述する必要あり
  • 設計書のフォーマット・ファイル形式に指定はなし、ファイル出力の必要もなし
  • 好きにやっていいとの指示

希望

  • Word や Excel で書きたくない
  • テキストベースで書いて、リポジトリ管理したい
  • ソースと配置をなるべく分けたくない
    • ソースはGitLab リポジトリで管理

  • GitLab の Wiki に Markdown で記述する

懸念点

  • Markdown では、画面設計書に必要な以下の内容を記述しにくい
    • 表形式
    • 定まったフォーマット(記述の自由度が高い)

打開策

  • 内容は、YAML で記述する
  • 表形式など表示を見やすくするために、YAML を読み込んで Markdown に変換する

YAML とは

人間が扱いやすい、構造化データ・オブジェクトを記述するためのデータ形式
公式

Swagger Spec の記述形式としても有名ですね。
Swagger Editorみたいな感じで、画面設計書も記述できるといいなーと思ったのが、今回の試みの発端です。

YAML が設計書の記述に合っているところ

  • 階層構造が記述できる
  • データが型を持つ
  • 改行を含んだデータを含めることができ、わかりやすく記述できる
  • JSON Schemaが設定できる

JSON Schema とは?

  • JSONの記述フォーマットを定義したもの
    公式

  • IDEに設定することで、入力補助やバリデーションチェックに利用できる

  • VSCode では、Extension YAML を使うことで、YAML のスキーマとして用いることができる

やったこと

JSON Schema を作成

1. 作成したいYAMLを一部分作成する
画面設計書なので画面要素1つ分の記述とか

2. 1. で作成したYAML を JSON に変換する
Webサービス yaml2json を利用
tQir2RbFy-chrome_2019-08-26_14-06-47.png

3. 2. で作成したJSONを元に、JSON Schema を作成
Webサービス JSON schema.neatを利用
入力した値を元にSchemaのスケルトンを作ってくれる
DlXN-yZ6f-chrome_2019-08-26_14-11-35.png

JSON Schema を VSCodeに設定

  1. Extension YAML を追加する
  2. YAMLのsetting にJSON Schema を設定する
setting.json
{
  "yaml.completion": true,
  "yaml.validate": true,
  "yaml.hover": true,
  "yaml.schemas": {
    "./screen.json": [
      "*.yml",
    ],
  },
  "yaml.format.enable": true,
}

手順は VSCodeで快適に設定ファイルを書く 参照

画面設計書(YAML)を書く

VSCode で YAML をゴリゴリ書いていきます。

  • Ctrl + space で入力補助がでます!(捗る!)
  • Scheme と合わない記述については、エラー表示されます
  • 入力パターンなど、Schema に追加したほうがよい内容は随時追加する → エラーが出るのでつぶしていく、の繰り返しで進めていきます R1sgPKJZt-Code_2019-08-26_14-28-37.png

YAMLをMarkdown に変換する

YAMLを読み込み、テンプレートを埋めて出力するスクリプト書きました

テンプレート

Markdown形式のテンプレートを作成します
記述しやすくするため、YAMLのキー名を日本語にしてたんですが、テンプレートでもそのまま参照できました

screen.hbs

# {{画面名}}
{{説明}}

## 画面イメージ
![]({{画像path}})

## 画面項目

  {{#each 画面項目}}

---

### {{名称}} ({{id}})

| ラベル     | 種類     | 入出力区分     | 表示/非表示     | 入力可/入力不可     | 型     | 桁数                                                                                | 表示フォーマット                       | 入力チェック    |
| ------- | ------ | --------- | ---------- | ------------ | ----- | --------------------------------------------------------------------------------- | ------------------------------ | ---------- |
| {{ラベル}} | {{種類}} | {{入出力区分}} | {{表示/非表示}} | {{入力可/入力不可}} | {{}} | {{#with 桁数}}{{#if min}} 最小:{{min}}{{/if}}{{#if max}}最大:{{max}}{{/if}}{{/with}} |  {{表示フォーマット}}  | {{入力チェック}} |

 {{#if 初期表示}}
 #### 初期表示

{{初期表示}}
 {{/if}}


 {{#if 説明}}
 #### 説明

{{説明}}
 {{/if}}

{{#if 備考}}
 #### 備考

{{備考}}
 {{/if}}

{{/each}}

感想

よかった点

  • 設計書書く時に、バリデーションチェックかかるのめっちゃいい
    • Schemaファイルを修正すると、すべての設計書で都度検証かかることで、記述が揃う
  • YAMLは複数行の文字列を入れやすい&見やすいので、設計書の主な記述である、表形式・自由記述のいずれの形式にも対応できる
    • ここにMarkdown入れられるので、記述効率も上がる(アウトラインは使えないけど、箇条書き・表形式など)
screen.yml

イベント:
  - id: init 
    名称: 初期処理
    項目id: 
    操作区分: その他
    画面遷移: 
    処理ID:
    入力:
    出力: 
    説明: | 
      - マスタデータ(Master)を用いて、紐づく入力項目の選択肢を生成する
      - 初期値を設定する
        - 画面入力情報が無い場合は、空白 or 初期表示の値を設定する
        - 画面入力情報が既にある場合は、該当する項目に保存されている値を表示する

いまいちな点

  • 一通り記述した後、ちょっとだけ修正したい時に、変換するのが面倒くさい・忘れがち
    • 何かでファイルの修正を感知してコマンド実行する的なものを仕込めば解決しそうだけど、今回至りませんでした…

今後やってみたいこと

  • 決まったキーワードと遷移先を定義しておいて、自動でリンク作成する的なこと
    • 設計書の相互参照って便利だしWikiの特性だと思うので使えるようにしてみたい
  • pdf に出力

参考

YAML書き方

https://qiita.com/tfrcm/items/5f8e4c5795ce41b214d1#%E3%82%B7%E3%83%BC%E3%82%B1%E3%83%B3%E3%82%B9%E9%85%8D%E5%88%97
https://magazine.rubyist.net/articles/0009/0009-YAML.html

JSON Schema書き方

https://www.ikemo3.com/manual/json-schema/
https://qiita.com/arumi8go/items/a9530cbd39ff545a7bbb

handlebars書き方

23
Help us understand the problem. What is going on with this article?
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
endk
システム開発の隙間や狭間にあるタスクを落穂拾いしています
stylez
WEB・業務システム、インフラ構築・運用監視まで、幅広い開発実績と経験豊富なエンジニアによる自社開発体制で、スピーディかつ高クオリティのシステム開発を手掛けています。AWSをはじめ各種クラウドやベンダーパートナーとして総合的なITサービスや、独自移行ツールを使ったマイグレーション、サーバーレスなシステム構築、コンテナを利用したDevOpsコンサルティングなどを提供しています。

Comments

No comments
Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account Login
23
Help us understand the problem. What is going on with this article?