はい。もちろんexcelやwordで書くわけではありません。
エンジニアたるものテキストベースで書きたいのです。
Swagger vs API Blueprint
ざっとググった感じだと、Swagger (OpenAPI Specifications)とAPI Blueprintというのが有力っぽい。
Swaggerはjsonまたはyamlで記述し、API Blueprintはmarkdownで記述するみたい。
Swaggerが機械寄り、API blueprintが人間寄りな印象。でもパッと見ではswaggerの方が読みやすいかなー。
試しにパスワード生成サービスのAPI仕様をそれぞれで書いてみる。
Swagger
swagger: '2.0'
info:
title: パスワード生成API
version: "1.0.0"
host: content.yosiopp.net
schemes:
- http
produces:
- application/json
- application/javascript
paths:
/app/passwd/:
get:
summary: |
生成したパスワードをjson形式で出力します。
`cb` が指定されている場合jsonpで出力します。
parameters:
- name: t
in: query
description: 文字種(0...英字, 1...英数, 2...英数+/, 未指定...英数記号)
type: number
- name: n
in: query
description: 文字数(default=12, max=256)
type: number
- name: cb
in: query
description: コールバックメソッド名
type: string
responses:
200:
description: |
`cb`を指定した場合、jsonpで出力する
schema:
type: string
examples:
application/javascript: |
callback("UaZJGlLcj63P")
application/json: |
{ "password": "UaZJGlLcj63P" }
yamlで書けるのは良いですね。
API Blueprint
FORMAT: 1A
# Group パスワード
## パスワード生成 [/app/passwd/{?t,n,cb}]
### パスワード生成 [GET]
#### 処理概要
* パスワードを取得する
+ Parameters
+ t: 0 (number, optional) - 文字種(0...英字, 1...英数, 2...英数+/, 3...英数記号)
+ Default: 3
+ n: 8 (number, optional) - 文字数(default=12, max=256)
+ Default: 12
+ cb: callback (string, optional) - コールバックメソッド名
+ Response 200 (application/json)
+ Attributes
+ password: UaZJGlLcj63P (string, required) - パスワード
こんな感じ。
cb指定した時のjsonpレスポンスの定義の仕方がよくわかんなかった。。
まとめ
個人的には記法はSwaggerの方が好きな感じでした。
指定の仕方に納得感があるというか、API Blueprintに比べてどう書いていいのかを推測しやすい感じ。
あと仕様がSwaggerの方が読みやすかったので。
ちなみに、AWS CloudFormationのServerless Application ModelでもAPI定義にSwaggerが使われてたりしますね。
参考URL
- http://dev.classmethod.jp/server-side/api-document-with-api-blueprint/
- http://blog.amedama.jp/entry/2016/03/08/202403
- http://iktakahiro.hatenablog.com/entry/2016/11/23/100000
- https://developer.ntt.com/ja/blog/c446d3f6-670d-4ba6-b589-5ec00600b95f
- https://aws.amazon.com/jp/blogs/aws/new-for-aws-lambda-environment-variables-and-serverless-application-model/