Zenn
🎼

Web API (OpenAPI) の探索やテストに便利な HttpRepl を使ってみた

2021/09/13に公開
.NET
Azure
Test
OpenAPI
Web API
tech

Channel 9 で Web API 兼英語のお勉強をしていたところ、HttpRepl という Web API 向けのツールが紹介されていました。

デモを見た感じ、なかなか面白そうだったので試してみました。公式ドキュメントおよび GitHub リポジトリは下記にあります。

環境

  • Windows 10
  • .NET Core

インストール方法

.NET Core SDK がインストールされた状態で、dotnet コマンドを一発叩けば OK です。

dotnet tool install -g Microsoft.dotnet-httprepl

試してみる

今回は、Swagger UI のデモサイトである https://petstore.swagger.io/ をお借りしてみます。

なお、本ツールは swagger.json などの OpenAPI description にアクセスできることが前提になっていますので、ご注意ください。

サイトへの接続

httprepl コマンドでツールを起動すると、サイトへの接続は未接続状態でツールが起動します。

connect コマンドを利用して、サイトに接続します。--verbose オプションを付与することで、動作の詳細ログを吐き出してみます。

(Disconnected)> connect https://petstore.swagger.io/ --verbose
Checking https://petstore.swagger.io/swagger.json... 404 NotFound

Checking https://petstore.swagger.io/swagger/v1/swagger.json... 404 NotFound

Checking https://petstore.swagger.io/openapi.json... 404 NotFound

Using a base address of https://petstore.swagger.io/
Unable to find an OpenAPI description
For detailed tool info, see https://aka.ms/http-repl-doc connect https://localhost:5001 --openapi /swagger/v1/swagger.json

ということで、普通に実行するといくつかのパスに OpenAPI description があるかアクセス試行します。が、今回のデモサイトではどこにも無かったので実質エラーになってしまいました。

デモサイトの OpenAPI description のパスは https://petstore.swagger.io/v2/swagger.json とのことなので、--openapi オプションを使って指定し、再度実行してみます。

(Disconnected)> connect https://petstore.swagger.io/ --verbose --openapi /v2/swagger.json
Checking https://petstore.swagger.io/v2/swagger.json... Found
Parsing... Successful

Using a base address of https://petstore.swagger.io/v2/
Using OpenAPI description at https://petstore.swagger.io/v2/swagger.json
For detailed tool info, see https://aka.ms/http-repl-doc

https://petstore.swagger.io/v2/>

無事接続できました😊

API を探索してみる

接続ができると、cd や ls コマンドを Linux の感覚で使うことで、API を探索することができます。

https://petstore.swagger.io/v2/> ls
.       []
pet     [POST|PUT]
store   []
user    [POST]

https://petstore.swagger.io/v2/> cd pet
/pet    [POST|PUT]

https://petstore.swagger.io/v2/pet> ls
.              [POST|PUT]
..             []
{petId}        [GET|POST|DELETE]
findByStatus   [GET]
findByTags     [GET]

https://petstore.swagger.io/v2/pet> cd petId
/pet/petId    [GET|POST|DELETE]

https://petstore.swagger.io/v2/pet/petId> ls
.             [GET|POST|DELETE]
..            [POST|PUT]
uploadImage   [POST]

Swagger UI 上の UI と比較すると、構造が対応づいていることは直感的に分かるかと思います。

API を実行してみる

実行するコマンドはそのまま HTTP のメソッドに対応しています。

GET

petId が 707 のペットをクエリ (GET) してみましょう。cd で pet に移動し、get の引数に 707 を付与すれば OK です。

https://petstore.swagger.io/v2/> cd pet
/pet    [POST|PUT]

https://petstore.swagger.io/v2/pet> get 707
HTTP/1.1 200 OK
Access-Control-Allow-Headers: Content-Type, api_key, Authorization
Access-Control-Allow-Methods: GET, POST, DELETE, PUT
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Type: application/json
Date: Sat, 11 Sep 2021 13:38:41 GMT
Server: Jetty(9.2.9.v20150224)
Transfer-Encoding: chunked

{
  "id": 707,
  "category": {
    "id": 0,
    "name": "CIELO LINDO"
  },
  "name": "CATITO",
  "photoUrls": [
    "FEO"
  ],
  "tags": [
    {
      "id": 0,
      "name": "CASA"
    }
  ],
  "status": "sold"
}

POST

POST 実行の際、既定では投げる中身を書くためのテキストエディタが開き、そこで保存した内容をリクエストとして投げます。

まずは、この時に使用するテキストエディタを設定します。今回は手抜きで notepad.exe ですｗ

https://petstore.swagger.io/v2/pet> pref set editor.command.default "C:\windows\system32\notepad.exe"

petId が 707 のペットの名前を変更するため、下記のように POST リクエストを実行してみます。

https://petstore.swagger.io/v2/pet> post -h Content-Type=application/json

テキストエディタが開くので、リクエストに応じた内容に整形します。

{
  "id": 707,
  "name": {
    "Value": "LINDO"
  },
}

保存して notepad.exe を閉じると、自動でリクエストが送信されます。

HTTP/1.1 200 OK
Access-Control-Allow-Headers: Content-Type, api_key, Authorization
Access-Control-Allow-Methods: GET, POST, DELETE, PUT
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Type: application/json
Date: Sat, 11 Sep 2021 13:50:02 GMT
Server: Jetty(9.2.9.v20150224)
Transfer-Encoding: chunked

{
  "id": 707,
  "name": "LINDO",
  "photoUrls": [
  ],
  "tags": [
  ]
}

なお、もちろん事前に中身 (JSON ファイル) を用意しておき、それを利用することもできます。その場合は、-f または --file オプションを付与し、ファイルパスを指定してあげます。

https://petstore.swagger.io/v2/pet> post -h Content-Type=application/json -f "C:\temp\test.json"
HTTP/1.1 200 OK
Access-Control-Allow-Headers: Content-Type, api_key, Authorization
Access-Control-Allow-Methods: GET, POST, DELETE, PUT
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Type: application/json
Date: Sat, 11 Sep 2021 14:00:31 GMT
Server: Jetty(9.2.9.v20150224)
Transfer-Encoding: chunked

{
  "id": 707,
  "name": "LINDO",
  "photoUrls": [
  ],
  "tags": [
  ]
}

終わりに

ということで、なかなか面白いツールでした。cd や ls を使うっていう発想はなかなか分かりやすいなーと。

手元での HTTP リクエストは Postman や VS Code 拡張機能なども便利ですが、Web API 向けにはこういうツールもあるんだなということは覚えておこうと思います！

Discussion