API Blueprintで作るAPI仕様書の例

PwmDocs_now.md

現在時刻取得 [/now]

現在時刻取得API [POST]

処理概要

• 現在の日時と時刻を返す。
• 日付・時刻形式は、YYYY-MM-DD HH:mm:ss (JST)とする。
• リクエストのPOSTパラメータにSlackのアクセストークンを含めない場合は、認証エラー(HTTP 403)を返す。

• Request (application/x-www-form-urlencoded)

  • Attributes + token: zaq123edcxsw (string, required) - Slackで発行されたトークン + team_id: T0001 (string) + team_domain: example (string) + enterprise_id: E0001 (string) + enterprise_name: Globular%20Construct%20Inc (string) + channel_id: C2147483705 (string) + channel_name: test (string) + user_id: U2147483697 (string, required) + user_name: PonzMild (string, required) + command: /now (string, required) - 入力したコマンド + text: xxxx (string, optional) - 入力したコマンドの後に与えた引数（任意） + response_url: https://hooks.slack.com/commands/1234/5678 (string) + trigger_id: 13345224609.738474920.8088930838d88f008e0 (string)

• Response 200 (application/json)

  • Attributes

    + response_type: ephemeral (string, required) - 閉じると消えるモードでポスト
    + text: `2018-01-05 14:58:22` (string, required) - 現在時刻 (pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$)
    

• Response 403 (application/json)

  • Attributes

    + response_type: ephemeral (string, required) - 閉じると消えるモードでポスト
    + text: 不正なリクエストです (string, required) - 認証エラーメッセージ
    

現在時刻取得API [GET]

処理概要

• 現在の日時と時刻を返す。
• 日付・時刻形式は、YYYY-MM-DD HH:mm:ss (JST)とする。

• Response 200 (application/json)

  • Attributes

    + response_type: ephemeral (string, required) - 閉じると消えるモードでポスト
    + text: `2018-01-05 14:58:22` (string, required) - 現在時刻 (pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$)
    

PwmDocsCreate.sh

#!/bin/bash

# 変数セット
DOC_APIB_FILE=PwmDocs.apib
DOC_HTML_FILE=PwmDocs.html
NOW_DTTM=`date "+%Y%m%d%H%M%S"`
LOG_FILE="${NOW_DTTM}_apib2html.log"

echo "[`date \"+%Y-%m-%d %H:%M:%S\"`] 処理開始" | tee -a logs/$LOG_FILE

# 既存のアウトプットファイルを削除
rm -f $DOC_APIB_FILE
rm -f $DOC_HTML_FILE

# ヘッダーとグループ名をつける
echo 'FORMAT: 1A' >> $DOC_APIB_FILE
echo '' >> $DOC_APIB_FILE
echo '# Group Workload-Manager' >> $DOC_APIB_FILE

# 分割済みのマークダウン形式ファイルを .apib ファイルに統合
cat ./md/*.md >> $DOC_APIB_FILE

# aglio で HTMLファイルに変換
# ERROR/WARNINGはログファイルに吐き出す
aglio -i $DOC_APIB_FILE -o $DOC_HTML_FILE >> logs/$LOG_FILE

# ERROR/WARNINGチェック
ERROR_ROWS=`grep -e "ERROR" logs/$LOG_FILE | wc -l`
WARNING_ROWS=`grep -e "WARNING" logs/$LOG_FILE | wc -l`

if [ ${ERROR_ROWS} -ne 0 ]; then
  echo "ERRORがあります!!"
  grep -e "ERROR" ./logs/$LOG_FILE
fi

if [ ${WARNING_ROWS} -ne 0 ]; then
  echo "WARNINGがあります!!"
  grep -e "WARNING" logs/$LOG_FILE
fi

echo "[`date \"+%Y-%m-%d %H:%M:%S\"`] 処理終了" | tee -a logs/$LOG_FILE
echo "APIドキュメント作成処理が完了しました。" | tee -a logs/$LOG_FILE

Gistでマークダウンのファイルそのまま貼り付けると、勝手に変換されちゃうのね。。。ソースコードそのままの方が良かったけど