Jdocを利用してJSON SchemaからAPIドキュメントを生成

@r7kamuraさん作のJdocを利用してJSON SchemaからAPIドキュメントを生成します

準備

Jdocについては@r7kamuraさん本人による下記のエントリをチェック

APIドキュメントを実装と乖離させないために - Qiita

サンプル

QiitaのAPI(v2)のJSON Schema( http://qiita.com/api/v2/schema?locale=en )から
template部分のみを抜粋して動作確認します。

サンプルJSON

{  
   "description":"このスキーマ定義では、Qiita API v2 のインターフェースをJSON Hyper Schema draft v4形式で表現しています。",
   "properties":{  
      "expanded_template":{  
         "description":"テンプレートを保存する前に変数展開後の状態をプレビューできます。Qiita:Teamでのみ有効です。",
         "links":[  
            {  
               "description":"受け取ったテンプレート用文字列の変数を展開して返します。",
               "href":"/api/v2/expanded_templates",
               "method":"POST",
               "rel":"create",
               "schema":{  
                  "properties":{  
                     "body":{  
                        "description":"テンプレートの本文",
                        "example":"Weekly MTG on %{Year}/%{month}/%{day}",
                        "type":"string"
                     },
                     "tags":{  
                        "description":"タグ一覧",
                        "example":[  
                           {  
                              "name":"MTG/%{Year}/%{month}/%{day}",
                              "versions":[  
                                 "0.0.1"
                              ]
                           }
                        ],
                        "items":{  
                           "properties":{  
                              "name":{  
                                 "type":"string"
                              },
                              "versions":{  
                                 "items":{  
                                    "type":"string"
                                 },
                                 "type":"array"
                              }
                           },
                           "required":[  
                              "name"
                           ]
                        },
                        "type":"array",
                        "uniqueItems":true
                     },
                     "title":{  
                        "description":"生成される投稿のタイトルの雛形",
                        "example":"Weekly MTG on %{Year}/%{month}/%{day}",
                        "type":"string"
                     }
                  },
                  "required":[  
                     "body",
                     "tags",
                     "title"
                  ]
               },
               "title":"create_expanded_template"
            }
         ],
         "properties":{  
            "expanded_body":{  
               "description":"変数を展開した状態の本文",
               "example":"Weekly MTG on 2000/01/01",
               "type":"string"
            },
            "expanded_tags":{  
               "description":"変数を展開した状態のタグ一覧",
               "example":[  
                  {  
                     "name":"MTG/2000/01/01",
                     "versions":[  
                        "0.0.1"
                     ]
                  }
               ],
               "items":{  
                  "properties":{  
                     "name":{  
                        "type":"string"
                     },
                     "versions":{  
                        "items":{  
                           "type":"string"
                        },
                        "type":"array"
                     }
                  },
                  "required":[  
                     "name"
                  ]
               },
               "type":"array",
               "uniqueItems":true
            },
            "expanded_title":{  
               "description":"変数を展開した状態のタイトル",
               "example":"Weekly MTG on 2015/06/03",
               "type":"string"
            }
         },
         "required":[  
            "expanded_body",
            "expanded_tags",
            "expanded_title"
         ],
         "title":"展開済みテンプレート"
      }
   },
   "required":[  
      "template"
   ],
   "title":"Qiita API v2 JSON Schema"
}

サンプルYaml

JSONをYAMLに変換します

• 変換スクリプト

---
description: "このスキーマ定義では、Qiita API v2 のインターフェースをJSON Hyper Schema draft v4形式で表現しています。"
properties:
  expanded_template:
    description: "テンプレートを保存する前に変数展開後の状態をプレビューできます。Qiita:Teamでのみ有効です。"
    links:
    - description: "受け取ったテンプレート用文字列の変数を展開して返します。"
      href: "/api/v2/expanded_templates"
      method: POST
      rel: create
      schema:
        properties:
          body:
            description: "テンプレートの本文"
            example: Weekly MTG on %{Year}/%{month}/%{day}
            type: string
          tags:
            description: "タグ一覧"
            example:
            - name: MTG/%{Year}/%{month}/%{day}
              versions:
              - 0.0.1
            items:
              properties:
                name:
                  type: string
                versions:
                  items:
                    type: string
                  type: array
              required:
              - name
            type: array
            uniqueItems: true
          title:
            description: "生成される投稿のタイトルの雛形"
            example: Weekly MTG on %{Year}/%{month}/%{day}
            type: string
        required:
        - body
        - tags
        - title
      title: create_expanded_template
    properties:
      expanded_body:
        description: "変数を展開した状態の本文"
        example: Weekly MTG on 2000/01/01
        type: string
      expanded_tags:
        description: "変数を展開した状態のタグ一覧"
        example:
        - name: MTG/2000/01/01
          versions:
          - 0.0.1
        items:
          properties:
            name:
              type: string
            versions:
              items:
                type: string
              type: array
          required:
          - name
        type: array
        uniqueItems: true
      expanded_title:
        description: "変数を展開した状態のタイトル"
        example: Weekly MTG on 2015/06/03
        type: string
    required:
    - expanded_body
    - expanded_tags
    - expanded_title
    title: "展開済みテンプレート"
required:
- template
title: Qiita API v2 JSON Schema

jdocでAPIドキュメントを生成

• 変換処理

jdoc schema.yml > api-doc.md

• 変換結果(Markdown)

※リストの2階層目は半角スペース1つで出力されていたので4つに置換してある

# Qiita API v2 JSON Schema
このスキーマ定義では、Qiita API v2 のインターフェースをJSON Hyper Schema draft v4形式で表現しています。

* [展開済みテンプレート](#展開済みテンプレート)
    * [POST /api/v2/expanded_templates](#post-apiv2expanded_templates)

## 展開済みテンプレート
テンプレートを保存する前に変数展開後の状態をプレビューできます。Qiita:Teamでのみ有効です。

### Properties
* expanded_body
    * 変数を展開した状態の本文
    * Example: `"Weekly MTG on 2000/01/01"`
    * Type: string
* expanded_tags
    * 変数を展開した状態のタグ一覧
    * Example: `[{"name"=>"MTG/2000/01/01", "versions"=>["0.0.1"]}]`
    * Type: array
* expanded_title
    * 変数を展開した状態のタイトル
    * Example: `"Weekly MTG on 2015/06/03"`
    * Type: string

### POST /api/v2/expanded_templates
受け取ったテンプレート用文字列の変数を展開して返します。

* body
    * テンプレートの本文
    * Example: `"Weekly MTG on %{Year}/%{month}/%{day}"`
    * Type: string
* tags
    * タグ一覧
    * Example: `[{"name"=>"MTG/%{Year}/%{month}/%{day}", "versions"=>["0.0.1"]}]`
    * Type: array
* title
    * 生成される投稿のタイトルの雛形
    * Example: `"Weekly MTG on %{Year}/%{month}/%{day}"`
    * Type: string

```
POST /api/v2/expanded_templates HTTP/1.1
Content-Type: application/json
Host: api.example.com

{
     "body": "Weekly MTG on %{Year}/%{month}/%{day}",
     "tags": [
       {
         "name": "MTG/%{Year}/%{month}/%{day}",
         "versions": [
           "0.0.1"
         ]
       }
     ],
     "title": "Weekly MTG on %{Year}/%{month}/%{day}"
}
```

```
HTTP/1.1 201 Created
Content-Type: application/json

{
     "expanded_body": "Weekly MTG on 2000/01/01",
     "expanded_tags": [
       {
         "name": "MTG/2000/01/01",
         "versions": [
           "0.0.1"
         ]
       }
     ],
     "expanded_title": "Weekly MTG on 2015/06/03"
}
```

• 変換結果(Markdown => HTML)

外部資料

• Jdoc - GitHub
• 全てがJSONになる