使用 swagger 定义 API:在参数中使用 JSON 的 GET 调用 [英] Defining an API with swagger: GET call that uses JSON in parameters
问题描述
我正在尝试创建一个合适的 REST API，并使用 Swagger (2.0) 对其进行记录.
I am trying to create a proper, REST API, and document it with Swagger (2.0).
所以，我有一个 API 调用，它是一个查询，即它不做任何更改，也不创建任何内容(幂等且安全).但它需要传入一个复杂的 JSON 参数(项目列表、2 或 3 组地址等).所以我正在做一个带有 URL 编码 JSON 参数的 GET.这似乎是正确的做法.
So, I have an API call that is a query, ie, it makes no changes and doesn't create anything (idempotent and safe). But it requires passing in a complex JSON parameter (list of items, 2 or 3 sets of addresses, etc). So I'm doing a GET with a parameter thats URL encoded JSON. That seems like the proper way to do it.
出于这个原因，我经常看到这样的 API，他们将其作为 POST 执行，但这是对 POST 动词的错误使用.
I see so often API's like this where they do it as a POST for this reason, but that's an incorrect use of the POST verb.
我看到很多 swagger API 都是这样做的...
I'm seeing lots of swagger API's that do this...
我不知道是否有一种方法可以使用 JSON 参数通过 Swagger 执行适当的 Rest API.当然，您可以将参数定义为字符串，然后将编码的 JSON 传递给它，但是 swagger 工具不知道它有一个架构/定义.
I can't figure out if there's a way to do a proper rest API with Swagger, using a JSON parameter. You can define the parameter as a string, of course, and pass your encoded JSON into it, but then the swagger tooling doesn't understand that there's a schema/definition for it.
swagger 是否无法正确记录这种调用?
Is swagger not able to properly document this kind of call?
推荐答案
OpenAPI 2.0 (Swagger 2.0)
OpenAPI 2.0 不支持查询字符串中的对象，它只支持原始值和原始数组.您最多可以将参数定义为 type: string，添加一个 JSON 值的 example，并使用 description 来记录 JSON对象结构.
OpenAPI 2.0 (Swagger 2.0)
OpenAPI 2.0 does not support objects in query strings, it only supports primitive values and arrays of primitives. The most you can do is define your parameter as type: string, add an example of a JSON value, and use description to document the JSON object structure.
swagger: '2.0'
...
paths:
/something:
get:
parameters:
- in: query
name: params
required: true
description: A JSON object with the `id` and `name` properties
type: string
example: '{"id":4,"name":"foo"}'
OpenAPI 3.x
查询字符串中的 JSON 可以使用 OpenAPI 3.x 进行描述.在 OAS 3 中，查询参数可以是原语、数组和对象，您可以指定这些参数应该如何序列化——扁平化为 key=value 对，编码为 JSON 字符串，等等.
OpenAPI 3.x
JSON in query string can be described using OpenAPI 3.x. In OAS 3, query parameters can be primitives, arrays as well as objects, and you can specify how these parameters should be serialized – flattened into key=value pairs, encoded as a JSON string, and so on.
对于包含 JSON 字符串的查询参数，使用 content 关键字为 JSON 数据定义一个 schema:
For query parameters that contain a JSON string, use the content keyword to define a schema for the JSON data:
openapi: 3.0.1
...
paths:
/something:
get:
parameters:
- in: query
name: params
required: true
# Parameter is an object that should be serialized as JSON
content:
application/json:
schema:
type: object
properties:
id:
type: integer
name:
type: string
这对应于下面的 GET 请求(在 URL 编码之前):
This corresponds to the following GET request (before URL encoding):
GET /something?params={"id":4,"name":"foo"}
或在 URL 编码后:
or after URL encoding:
GET /something?params=%7B%22id%3A4%2C%22name%22%3A%22foo%22%7D
Swagger UI 用户注意事项:
Swagger UI 3.23.8+ 和 Swagger Editor 3.6.34+ 支持带有 content 的参数.
Note for Swagger UI users:
Parameters with content are supported in Swagger UI 3.23.8+ and Swagger Editor 3.6.34+.
早期版本的 UI/编辑器的解决方法:
将参数定义为 type: string 并添加 JSON 数据的 example.您失去了为查询字符串描述 JSON 模式的能力，但尝试一下"是可以的.会工作.
Workaround for earlier versions of UI/Editor:
Define the parameter as just type: string and add an example of the JSON data. You lose the ability to describe the JSON schema for the query string, but "try it out" will work.
parameters:
- in: query
name: params
required: true
schema:
type: string # <-------
example: '{"id":4,"name":"foo"}' # <-------
这篇关于使用 swagger 定义 API:在参数中使用 JSON 的 GET 调用的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
