用swagger: GET调用定义一个API，该调用在参数中使用JSON

Question

我正在尝试创建一个适当的REST API，并使用Swagger（2.0）记录它。

所以，我有一个API调用，它是一个查询，即它不做任何更改，也不创建任何内容（幂等和安全）。但它需要传入一个复杂的JSON参数（项目列表、2或3组地址等）。所以我用URL编码的JSON参数进行GET。这似乎是正确的做法。

出于这个原因，我经常看到这样的 API，他们将其作为 POST 进行，但这是对 POST 动词的错误使用。

我看到很多大摇大摆的API都这样做…

我想不出是否有办法用一个JSON参数，用Swagger做一个合适的rest API。当然，您可以将参数定义为一个字符串，并将您编码的JSON传递给它，但是swagger工具不知道它有一个模式/定义。

swagger不能正确记录这种呼叫吗？

Answer 1

对于.Net和Swashbuckle（在3.0上测试），我有一个实现IModelBinder接口的通用类JsonModelBinder。类的用法如下：

public IActionResult SomeAction(
        [FromRoute] int id, 
        [FromQuery][ModelBinder(BinderType = typeof(JsonModelBinder<SomeModel>))] SomeModelquery query) => {}

我创建了执行以下操作的操作过滤器：

• 从模型的属性中删除虚张声势创建的参数
• 添加字符串类型的查询参数

结果在 Swagger 中，我有一个文本字段，我可以在其中插入 json 和测试请求

public class JsonModelBinderOperationFilter : IOperationFilter
{
    public void Apply(Operation operation, OperationFilterContext context)
    {
        if (operation.Parameters == null || context.ApiDescription.HttpMethod != HttpMethod.Get.ToString())
            return;
        //Find json parameters
        var jsonGetParameters = context.ApiDescription.ActionDescriptor.Parameters.Cast<ControllerParameterDescriptor>()
            .Where(p => p.ParameterInfo.CustomAttributes.Any(c => c.AttributeType == typeof(ModelBinderAttribute) && c.NamedArguments.Any(IsJsonModelBinderType))).ToArray();

        if (jsonGetParameters.Length > 0)
        {
            //Select parameters names created by Swagger from json parameters
            var removeParamNames = new HashSet<string>(context.ApiDescription.ParameterDescriptions.Where(d => jsonGetParameters.Any(p => p.Name == d.ParameterDescriptor.Name)).Select(p => p.Name));
            //Create new Swagger parameters from json parameters
            var newParams = jsonGetParameters.Select(p => new NonBodyParameter()
            {
                In = "query",
                Name = p.Name,
                Type = "string",
                Description = "Json representation of " + p.ParameterType.Name
            });
            //Remove wrong parameters and add new parameters
            operation.Parameters = operation.Parameters.Where(p => p.In != "query" || !removeParamNames.Contains(p.Name)).Concat(newParams).ToList();
        }
    }

    private static bool IsJsonModelBinderType(CustomAttributeNamedArgument arg)
    {
        var t = arg.TypedValue.Value as Type;
        return t != null && t.GetGenericTypeDefinition().IsAssignableFrom(typeof(JsonModelBinder<>));
    }
}

注意事项:

< li >我使用IsAssignableFrom，因为我有从JsonModelBinder派生的类。不继承可以省略 < li >如果您的活页夹不是通用的，您也可以省略GetGenericTypeDefinition < li >此解决方案不检查参数名冲突，尽管如果API符合常识，您就永远不应该检查参数名冲突

Answer 2

OpenAPI 2.0不支持查询字符串中的对象，只支持原语值和原语数组。您最多可以将参数定义为< code>type: string，添加一个JSON值的< code>example，并使用< code>description来记录JSON对象结构。

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"}'

查询字符串中的JSON可以使用OpenAPI 3.x进行描述。在OAS 3中，查询参数可以是原语、数组以及对象，您可以指定这些参数的序列化方式——将其展开为key=value对，编码为JSON字符串，等等。

对于包含JSON字符串的查询参数，使用Content关键字为JSON数据定义架构：

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编码之前）：

GET /something?params={"id":4,"name":"foo"}

或在URL编码后:

GET /something?params=%7B%22id%3A4%2C%22name%22%3A%22foo%22%7D

Swagger UI用户注意:< br > Swagger UI 3 . 23 . 8和Swagger Editor 3.6.34支持带有< code>content的参数。

早期版本的UI/Editor的解决方法:< br >将参数定义为< code>type: string并添加JSON数据的< code>example。您失去了描述查询字符串的JSON模式的能力，但是“尝试一下”将会起作用。

      parameters:
        - in: query
          name: params
          required: true
          schema:
            type: string                    # <-------
          example: '{"id":4,"name":"foo"}'  # <-------