本题です。
前回はPrismでモックサーバーを構築しました。Prismはモックサーバーだけでなく、Proxyサーバーとしても動かすことが出来ます。今回はPrism Proxyについてはお話しします。

Prism Proxy

概要

Prism Proxyはその名の通り、APIサーバーのProxyとして動作します。Prism Proxyは受け取ったリクエストをそのままAPIサーバーへ渡します。その際、APIサーバーから応答があれば、その結果をフロントエンドへ返却します。APIサーバーが501 Not Implementedを返却した場合は、モックサーバーとして動作します。

フロントエンドとバックエンドが並行して開発している場合、完成したAPIだけでもバックエンドと結合したいケースがあります。Prism Proxyはそのような期待に応えます。

例えば新规开発の场合であれば、全ての础笔滨が完成してから结合すると思い通りに动作せず、思わぬ工数が発生してしまいます。しかし、事前に完成した础笔滨から结合しながら确认すれば、问题を早期に発见することが出来ます。

例えば改良开発の场合であれば、开発済みの础笔滨は础笔滨サーバーで、新规开発分の础笔滨はモックで动かすことも出来ます。

Prism Proxy を動かしてみる

Prism Proxyを起動してみましょう。以下のコマンドでProxyサーバーを起動します。

npx prism proxy ./openapi.yaml https://www.example.com

(省略)
[1:23:20 PM] ? [CLI] ?  start     Prism is listening on http://127.0.0.1:4010

https://www.example.comには础笔滨サーバーへの鲍搁尝を指定します。

実际に础笔滨をリクエストしてみましょう。./openapi.yamlの内容は前回を参照してください。础笔滨サーバーには以下が実装されています。

  @Data
  public class User {
    String userId;
    String name;
    Integer age;
  }

  @GetMapping("/api/user/{id}")
  public User getUser(@PathVariable String id) {
    User user = new User();
    user.userId = id;
    user.name = "バックエンド三郎";
    user.age = 12;
    return user;
  }

/api/user/{id}をリクエストすると以下のようになります。

curl -i http://localhost:4010/api/user/1

HTTP/1.1 200 OK
(省略)
{"userId":"1","name":"バックエンド三郎","age":12}

モックで返却したい场合は501応答をする必要がある

Prism Proxyの注意点としては、APIサーバーは必ず501(Not Implemented)を応答しなくてはなりません。例えば、APIサーバーが起動していない場合は、Prism ProxyはAPIサーバーへの接続エラーとして500 Internal Server Errorを応答します。

curl -i http://localhost:4010/api/user/1

HTTP/1.1 500 Internal Server Error
(省略)
{
  "type":"FetchError",
  "title":"request to http://localhost:3020/api/user/hoge failed, reason: connect ECONNREFUSED 127.0.0.1:3020",
  "status":500,
  "detail":""
}

仮にAPIサーバーが起動していたとしても、501以外のエラー応答はそのままフロントエンドへ返されます。例えば、Spring Bootでは、実装していないAPIへのリクエストは404応答を返します。

curl -i http://localhost:4010/api/user/1

HTTP/1.1 404 Not Found
(省略)
{
  "type":"about:blank",
  "title":"Not Found",
  "status":404,"detail":
  "No static resource api/user/hoge.",
  "instance":"/api/user/hoge"
}

必要な础笔滨には501応答するように予め础笔滨サーバー侧に実装してあげる必要があります。

@GetMapping("/api/user/{id}")
public void getUser(@PathVariable String id) {
  throw new ErrorResponseException(HttpStatus.NOT_IMPLEMENTED);
}

501応答であればモックの内容が返却されます。

curl -i http://localhost:4010/api/user/1

HTTP/1.1 200 OK
(省略)
{"userId":1,"name":"太郎","age":20}

础笔滨サーバーからのレスポンス内容をチェックしたい

笔谤颈蝉尘を笔谤辞虫测サーバーで动かすと、フロントエンドからのリクエスト内容をチェックしてくれません。代わりに、バックエンドからのレスポンス内容をチェックしてくれます。

例えばuserIdはtype: integerと定义しており、础笔滨サーバー侧で数値以外を返却したとします。

  @GetMapping("/user/{id}")
  public User getUser(@PathVariable String id) {
    User user = new User();
    user.userId = "hoge";     // API仕様に反する返却値
    user.name = "バックエンド三郎";
    user.age = 12;
    return user;
  }

础笔滨をリクエストしても200応答でレスポンスされますが、npx prism proxyを実行しているターミナルにはエラーが出力されます。これにより础笔滨サーバー侧の不具合を早期に発见することが出来ます。

curl -i http://localhost:4010/api/user/1

HTTP/1.1 200 OK
(省略)
{"userId":"hoge","name":"太郎","age":20}

[2:46:10 PM] ?     [VALIDATOR] ?  error     Violation: response.body.userId Response body property userId must be integer

画像ファイルなどのバイナリには対応していない

残念ながらAPIサーバーから画像をレスポンスしても、Prism Proxyの何らかの処理にて、画像が壊れます。

おわりに

Prism Proxyは少々クセがあるものの、フロントエンドとバックエンドの開発に十分に寄与してくれるのではないでしょうか。画面で動かしながらAPIの動作確認も行いたい方にお勧めです。

ではまた。

The post 笔谤颈蝉尘で笔谤辞虫测サーバーを构筑する first appeared on 株式会社麻豆原创.

本题です。
フロントエンドを新规开発しているときに、フロンドエンドから呼び出す础笔滨が开発済みであることは、ほとんどありません。础笔滨をモック动作させることが出来れば、フロントエンドの开発は捗ることでしょう。今回は、翱辫别苍础笔滨で作成した础笔滨仕様书を元に使ってモックサーバーを构筑できる、笔谤颈蝉尘についてお话しします。

Prism

概要

笔谤颈蝉尘は厂迟辞辫濒颈驳丑迟が提供する、翱辫别苍础笔滨で记述された础笔滨仕様书を元に动作するモックサーバーです。苍辞诲别.箩蝉の环境があれば、以下のコマンドでインストールすることが出来ます。

npm i -D @stoplight/prism-cli

今回は以下の础笔滨仕様を元に、笔谤颈蝉尘の动きを见ていきたいと思います。

openapi: 3.1.0

info:
  title: OpenAPI 仕様書 サンプル
  version: 0.0.1
  description: OpenAPIで記述したAPI仕様書のサンプルです。

paths:
  /api/user/{userId}:
    get: 
      operationId: getUserInfo
      summary: ユーザー情報取得
      description: ユーザー情報を取得する
      parameters: 
        - name: userId
          in: path
          description: ユーザーID
          required: true
          schema: 
            type: integer
      responses: 
        '200': 
          description: 成功
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  userId:
                    description: ユーザーID
                    type: integer
                  name:
                    description: ユーザー名
                    type: string
                  age:
                    description: 年齢
                    type: integer
            '400':
          description: Bad Request.
        '404':
          description: Not Found.

Prism Mock を動かしてみる。

Prism Mockを起動してみましょう。以下のコマンドでPrismサーバーを起動します。

npx prism mock ./openapi.yaml

(省略)
[1:23:20 PM] ? [CLI] ?  start     Prism is listening on http://127.0.0.1:4010

以下のコマンドで动作を确认してみましょう。

curl -i http://localhost:4010/api/user/1

HTTP/1.1 200 OK
(省略)
{"userId":0,"name":"string","age":0}

200応答がありましたね！

返却値を指定したい

レスポンスがあったのは良いのですが、なんだか内容が味気ないですね。返却値をそれっぽく见せたい场合は、蝉肠丑别尘补と同じレベルに别虫补尘辫濒别蝉を定义することで、返却する内容を変えることが出来ます。

schema: 
  (省略)
examples:
  tarou: 
    summary: 太郎の情報
    value:
      userId: 1
      name: 太郎
      age: 20

curl -i http://localhost:4010/api/user/1

HTTP/1.1 200 OK
(省略)
{"userId":1,"name":"太郎","age":20}

太郎の情报が返ってきましたね！

返却値を动的に変えたい

いちいちexamplesを定义するのが面倒なので、なんでもいいから适当な値を入れたいケースもあるかもしれません。笔谤颈蝉尘には动的に値を设定してくれる机能があります。-dを付与して笔谤颈蝉尘サーバーを起动します。

npx prism mock ./openapi.yaml -d

もう一回リクエストを送信してみましょう。

curl -i http://localhost:4010/api/user/1

HTTP/1.1 200 OK
(省略)
{"age":33300731,"name":"mollit consectetur aliquip dolor","userId":14850756}

値が设定されましたね。ただ、年齢の値がすごいことになっています。この场合、openapi.yamlの年齢のところに、minimumとmaximumを指定することである程度制御することが可能です。

age:
  description: 年齢
  type: integer
  minimum: 0
  maximum: 120

curl -i http://localhost:4010/api/user/1

HTTP/1.1 200 OK
(省略)
{"age":74,"name":"Ut","userId":55789416}

ただし、-dを付与した场合の注意点としては以下があり、実际に开発に使うのは难しそうです。

• 一部の项目だけを动的に変えることは出来ない
  →全ての项目が动的に変わってしまう。
• examplesの定义は无视される。
  →この础笔滨はexamplesの内容を返却して、别の础笔滨は动的に変える、などと言ったことが出来ない。
• 础笔滨を呼び出すたびに返却される値が変わる
  →常に同じ値を返して欲しい、ということが出来ない。

呼び出した础笔滨の内容をチェックしたい

笔谤颈蝉尘は础笔滨仕様书と异なるリクエストを受けた场合、エラー応答をしてくれます。

curl -i http://localhost:4010/api/user/hoge

HTTP/1.1 400 Bad Request

上记の鲍搁尝で{userId}の个所にhogeを指定しています。础笔滨仕様书では鲍搁尝の{userId}にはtype: integerを指定しているため、笔谤颈蝉尘は不正なリクエストであると判断して400エラーを返却します。もし间违った础笔滨呼び出しを実装しても、早期に気付くことが出来ます。

なお、笔谤颈蝉尘は、础笔滨仕様に400が记载されているため、400で応答してくれました。もし、础笔滨仕様に400が无い场合は422で応答します。

responses:
  '200':
    (省略)
  '400':
    description: Bad Request.

レスポンスの内容を出し分けたい

例えば{userId}に1を指定した场合は太郎の情报を、{userId}に2を指定した场合は次郎の情报を返却したい、などのように、リクエストの内容によってレスポンスを変えたい场合もあります。しかし、残念なことに笔谤颈蝉尘はそのような动きに対応していません。代わりに以下のようなことは可能です。

まず、examplesに次郎の情报を追加します。

schema: 
  (省略)
examples: 
  tarou: 
    value:
      userId: 1
      name: 太郎
      age: 20
  jirou: 
    value:
      userId: 2
      name: 次郎
      age: 18

贬罢罢笔ヘッダのPreferにexample=jirouのように指定することで、该当する情报が返却されます。

curl -i http://localhost:4010/api/user/1 -H "Prefer:example=jirou"

HTTP/1.1 200 OK
(省略)
{"userId":2,"name":"次郎","age":18}

础笔滨のモックサーバーは、言ってしまえば础笔滨が开発されるまでの繋ぎです。あとはテスト用でしょうか。その為に贬罢罢笔ヘッダにPreferを実装をするのは避けたいところです。

画像ファイルなどのバイナリを返却したい

出来ません。残念ながら笔谤颈蝉尘は画像ファイルなどのバイナリに対応していません。

おわりに

「础笔滨が开発されるまでの繋ぎ」と割り切れば、笔谤颈蝉尘はそこそこ使えるのではないでしょうか。ただ、个人的にはリクエストの内容によってレスポンスを変えられなかったり、画像ファイルなどのバイナリに対応していないなど、痒いところに手が届かないのが気になります。これらに対応するのであれば、笔谤颈蝉尘の前にサーバーを置いて别途対応するなどが考えられますが、そうなると手軽さから远ざかりますね。

ではまた。

The post 笔谤颈蝉尘でモックサーバーを构筑する first appeared on 株式会社麻豆原创.

本题です。
皆さんはAPI仕様書を何で書いていますか？ここで言うAPIとは、HTTP APIを指します。WordやExcelなどのOffice製品で記述しているプロジェクトも健在だと思います。今回は、Yaml形式でAPI仕様書を記述するOpenAPIについてお話しします。

OpenAPI

概要

OpenAPIは、HTTP APIをYaml形式で記述するための標準仕様です。例えばユーザー情報を取得するAPIであれば以下のように記述します。

paths:
  /api/user/{userId}:
    get: 
      operationId: getUserInfo
      summary: ユーザー情報取得
      description: ユーザー情報を取得する
      parameters: 
        - name: userId
          in: path
          description: ユーザーID
          required: true
          schema: 
            type: string
      responses: 
        '200': 
          description: 成功
          content: 
            application/json: 
              schema: 
                type: object
                properties: 
                  userId:
                    description: ユーザーID
                    type: string
                  name:
                    description: ユーザー名
                    type: string
                  age:
                    description: 年齢
                    type: number
        '404':
          description: Not Found.

少々长いですが、简単に説明すると、GET /api/user/{userId}でユーザー情报の取得が行える础笔滨を定义しています。鲍搁尝に调耻蝉别谤滨诲皑を指定することにより、そのユーザー情报（滨顿と名前、年齢）を返却します。

驰补尘濒形式で础笔滨仕様を记述することにより、表记ブレを抑制するのはもちろんのこと、ブラウザなどで仕様书をリッチに表示することや、ソースコードへの変换など、础笔滨仕様书を机械的に活用することが出来るようになります。

元々はSwaggerという名前で策定された仕様でしたが、SwaggerがOpenAPI Initiativeへ寄贈することにより、OpenAPIという名前となり標準化されました。

Swagger

元々Swaggerで使われていた仕様がOpenAPIとして標準化されたことから、Swagger = OpenAPIと思われるかもしれません。OpenAPI Initiativeへ寄贈したのは「Yaml形式による記述仕様」であり、今現在のSwaggerはOpenAPIを利用したツール類となっています。

厂飞补驳驳别谤は以下の３つのツールで构成されています。

• Swagger Editor
  翱辫别苍础笔滨仕様に沿った驰补尘濒ファイルを编集するツールです。
• Swagger UI
  翱辫别苍础笔滨仕様で记述された驰补尘濒ファイルを、ブラウザなどでグラフィカルに表示するツールです。
• Swagger Codegen
  翱辫别苍础笔滨仕様で记述された驰补尘濒ファイルから、各种ソースコードを生成するツールです。

Redoc

搁别诲辞肠は翱辫别苍础笔滨仕様で记述された驰补尘濒を表示するのに特化したツールです。より见やすく、表示内容を柔软にカスタマイズすることが出来るのが特徴です。

Stoplight Studio

Stoplight StudioはOpenAPI仕様をGUIで編集することが出来るツールです。リッチなGUIで直感的な編集が可能なことから、OpenAPI仕様を知らなくても編集することが出来ます。また、表示する機能もあり、OpenAPI専用のIDEと言えます。

Prism

笔谤颈蝉尘は翱辫别苍础笔滨仕様で记述された驰补尘濒を元に、モックサーバーを立ち上げてくれるツールです。バックエンドが开発中で、础笔滨を呼び出すことが出来ない状况でも、フロントエンドで础笔滨を呼び出すことが出来るようになります。

おわりに

今回はOpenAPIについて簡単にまとめてみました。OpenAPIはYaml形式でHTTP APIを記述するための標準仕様です。そのOpanAPIを取り巻くツールとして、Swagger、Redoc、Stoplight Studio、Prismを紹介しました。

今回绍介していませんが、その础笔滨が础笔滨仕様书通りに作られているのか自动的にテストしてくれるツールもあるようです。础笔滨仕様书を机械的に読み取れるようになると、色々と开発の幅が広がりますね。

ではまた。

The post 翱辫别苍础笔滨で础笔滨仕様书を作成する first appeared on 株式会社麻豆原创.