8

200 OK を返し、HTML を返す API 呼び出しがあります。これを API ドキュメントに追加したいと思います (特に、dredd を使用して検証し、期待される応答本文を提供しない限り、テストは失敗します)。Swaggerでこれを行うにはどうすればよいですか?

--- 詳細 --- API 呼び出しに対する私の応答は 200 OK で、応答本文は 1 行です。

<html><body>You are being <a href="https://my.domain.com/users/sign_in">redirected</a>.</body></html>

Blueprint の Response Body は、次の形式で簡単に定義できます。

 + Response 302 (text/html; charset=utf-8)

     + Body

         `<html><body>You are being <a href="https://my.domain.com/users/sign_in">redirected</a>.</body></html>`

しかし、Swagger でこれを行う方法がわかりません。私が見つけることができるほとんどすべての例は、(当然のことながら) application/json 応答用であり、この種の応答の正しい構文を推測するのに苦労しています。

私のドキュメントの関連するswaggerテキストは次のとおりです（これまでのところ、応答本文を指定していないため、応答本文が である必要があるため、空の本文で dredd が失敗します<html><body>You are being <a href="https://my.domain.com/users/sign_in">redirected</a>.</body></html>）：

# this is my API spec in YAML
swagger: '2.0'
info:
  title: My API (Swagger)
  description: blablabla
  version: "1.0.0"
# the domain of the service
host: my.domain.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /
produces:
  - application/json; charset=utf-8
paths:
  /users/password:
    post:
      summary: Password Reset
      description: |
        Handles Reset password for existing user.
      consumes:
        - application/x-www-form-urlencoded
      produces:
        - text/html; charset=utf-8
      parameters:
        - name: "user[email]"
          description: email
          in: formData
          required: true
          type: string
          default: "user@gmail.com"
      tags:
        - Reset Password
      responses:
        200:
          description: Success

これについて何か提案があればコメントしてください。ありがとう！

4

2 に答える 2

12

理解した。応答オブジェクトには「examples」というフィールドがあり、API 応答に例を表示できます。

構文は仕様に明確に示されています。基本的には、応答例の MIME タイプを識別する必要があることを示しています。私の場合は text/html で、値は実際のテキストです。

このように：

    responses:
      200:
        description: success and returns some html text
        examples:
          text/html: 
            <html><body>Your HTML text</body></html>

それでおしまい。dredd がこの値を取得して比較することを知っているかどうかは別の話です。彼らのドキュメントでは、JSON 以外の応答はプレーン テキストとして検証されるため、これは機能すると述べています。

これが役に立ったことを願っています。

于 2016-08-14T23:02:59.363 に答える