はい。もちろん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