OutSystemsのREST API作成機能(3) APIドキュメント(自動作成)

REST, Swagger, OutSystems, Web API

OutSystemsで作成したREST APIですが、実は、API仕様書が自動で作成されます。

しかもSwagger。ということでさっそく試してみました。題材は前回までに自分で作ったREST APIとします。

シリーズ一覧

公式情報

Document Exposed  REST APIs

まずはドキュメントを有効化(デフォルトで有効です)

REST直下に作成したAPI(メソッドでなく下図の「Customers」に相当)の「Documentation」をYesに。

デフォルトで「Yes」なので確認するだけでいいです。

WS000009

1-Click Publishして、動作確認します。

REST APIのデフォルトURLを開いてみるとSwagger画面が表示されます。これは楽です。

APIのプログラミングをしたうえで、JSONでドキュメント書くのはしんどいですからね。

OutSystemsCloudSwagger WS000000
ちなみにドキュメントを有効にしていないと404が返ってきます。

WS000008

Swaggerデモサイトでも動作確認

「Authentication」の下あたりにjsonファイルのURLがあったのでデモサイトで、上のテキストボックスにURLを貼り付けて「Explore」するとこちらでもちゃんと表示されます。つまり、OutSystemsで機能公開すると同時にスクリプトでjsonを自動取得して他サイトでドキュメント公開という流れでもできますね。

ちなみに、私の作ってみたAPIはBasic認証かけているのですが、認証渡してのAPI動作確認もSwagger上でできるようです。

http://petstore.swagger.io/

ドキュメントのブラッシュアップ

細かいところは上の公式情報で確認していただきたいですが、認証方法の説明と下記4か所の説明をプロパティで設定できます。

  • 　REST API(Service StudioでRESTの直下)
  • 　各メソッド
  • 　パラメータ
  • 　戻り値

Markdown記法なるものも可能らしいので戻り値の説明でテストしてみました。

なお、なぜか戻り値の説明だけ変更してもドキュメントに反映しなかったので、一緒にメソッドの説明とかも変えてください。

REST API開発規約で、この辺を正しく設定すれば、API仕様書作成は確認だけの工数で大丈夫そう。ASP.NETなんかでも最近はREST API開発支援機能が充実してきていますが、これならよほど慣れている人以外はOutSystemsのほうが早くできそうな気がします。

WS000006 WS000007