PHP で REST API の簡単なドキュメントをMarkdown形式で生成してくれるプログラムを作った


はじめに
--
未だ全然作りかけなので公開するか迷いましたが取り敢えず出してみました。
何でPHPで生成するのかというと自分がPHPが好きだからです。リポジトリは[こちら](https://github.com/ken880guchi/GenerateRestAPIDocument)！！
また、ご助言等頂けると大変助かります。

どう使うの？
--

任意の場所に下記の構成でファイルを配置します。

```
|+ Documents // ドキュメント定義用ファイル格納ディレクトリ
 |- search.php // ドキュメント定義用ファイル (ファイル名はご自由に！)
|- GenerateRestDocument.php // ドキュメント生成プログラム
```

次にDocumentsディレクトリ配下に格納したドキュメント定義用ファイルを作成します。
上記の例で言うと **search.php** がそれにあたります。

中身の記述はphpの配列での記述になります。具体的には下記のように記述します。

```php
<?php

$document = [
	'name'      => '施設情報検索',
	'overview'  => '施設の情報を検索します。',
	'method'    => 'PUT',
	'url'       => '/api/v1/hotels/search',
	'request'    => [
		[
			'item'        => 'checkin',
			'type'        => 'string',
			'require'     => true,
			'description' => 'チェックイン日',
		],
		[
			'item'        => 'checkout',
			'type'        => 'string',
			'require'     => true,
			'description' => 'チェックアウト日',
		],
		[
			'item'        => 'adult',
			'type'        => 'number',
			'require'     => true,
			'description' => '大人の人數',
		],
		[
			'item'        => 'child',
			'type'        => 'number',
			'require'     => false,
			'description' => '子供の人數',
		],
	],
	'response'    => [
		[
			'item' => 'hotels',
			'type' => 'array',
			'description' => '施設情報',
			'structure' => [
				[
					'item'        => 'id',
					'type'        => 'number',
					'description' => '施設ID',
				],
				[
					'item'        => 'name',
					'type'        => 'string',
					'description' => '施設名',
				],
				[
					'item'        => 'area',
					'type'        => 'object',
					'description' => '施設地域情報',
					'structure'   => [
						[
							'item'        => 'regionName',
							'type'        => 'string',
							'description' => '地方名',
						],
						[
							'item'        => 'prefectureName',
							'type'        => 'string',
							'description' => '県名',
						],
					],
				],
				[
					'item'        => 'address',
					'type'        => 'string',
					'description' => '施設住所',
				],
			],
		],
	],
];
```

項目毎の説明は下記の通りです。

| key  | 説明                |
|------|--------------------|
| name | API の名前          |
| overview | API の概要          |
| method | API リクエスト時に用いるメソッド          |
| url | API の URL         |
| request | API リクエスト時に用いるパラメーター |
| > item | パラメーターのkey |
| > type | パラメータの型 |
| > require | パラメーターが必須か |
| > description | パラメーターの説明 |
| response | API レシポンス時の値 |
| > item | レスポンスのkey |
| > type | レスポンスの型 |
| > description | レスポンスの説明 |
| > structure | 配列やオブジェクト型の場合に使用します。後程記載する結果を御覧頂くと解りやすいかもです。 |

ドキュメント用のファイルが準備出来たら下記のように GenerateRestAPIDocument.php を実行してみてください。

```sh
# ドキュメント生成の実行
php GenerateRestDocument.php
```

下記に記載している実行結果の文字列が出力されるはずです(これは.mdファイルに出力するように今後します。)

Request parameter の項目で頭に * が付与されている項目は必須項目を表しています。
また、Response parameter の > は項目が存在する階層を表しています。

実行結果
--

施設情報検索  [PUT] /api/v1/hotels/search
--
施設の情報を検索します。

Request parameter
--

| item | type | description |
|------|------|-------------|
| *checkin | string | チェックイン日 |
| *checkout | string | チェックアウト日 |
| *adult | number | 大人の人數 |
| child | number | 子供の人數 |

Response parameter
--

| item | type | description |
|------|------|-------------|
| hotels | array | 施設情報 |
| >id | number | 施設ID |
| >name | string | 施設名 |
| >area | object | 施設地域情報 |
| >>regionName | string | 地方名 |
| >>prefectureName | string | 県名 |
| >address | string | 施設住所 |


これから
--

- README を記載する
- 生成したMarkdown文字列をファイルに纏めて吐き出せるようにする
- HTML でも吐き出せるようにする