Swagger 数据类型不生成文档

Question

我在 Swagger 中有以下代码，

@Path("/v1")
    @ApiOperation(value = "POST - Some Value", nickname = "post-funtion", consumes = "application/json", produces = "text/html; charset=UTF-8", tags = {
            "Some Controller" })
    @ApiImplicitParams({
            @ApiImplicitParam(name = "Authorization", paramType = "header", dataType = "string", format = "JWT", required = false, value = "A User Service JWT"),
            @ApiImplicitParam(name = "Request", value = "Request Object", paramType = "body", dataType = "org.pkg.SomeRequest", required = true) })
    @ApiResponses({
            @ApiResponse(code = 200, message = "Value Added", response = SomeResponse.class) })
private Object retrieveByName(Request request, Response response)
{
    return new RetrieveByNameRqstHandler(catalogService, request, response).handle();
}

代码应该根据数据类型自动生成默认 json 请求，在本例中为 "org.pkg.SomeRequest" 但没有生成任何内容。相反，如果我将 "org.pkg.SomeRequest" 更改为 "org.pkg.SomeResponse"，则会为此生成默认的 JSON。有人可以帮我吗？

考虑类 SomeRequest、SomeResponse 具有相同的代码。这是我在数据类型中使用 "org.pkg.SomeRequest" 的图像

这是我在 dataType

中使用 "org.pkg.SomeResponse" 的图像

Answer 1

根据关于 Swagger 核心项目的 GitHub issue，如果您添加注释 @ApiImplicitParam 应该可以解决您的问题。

@ApiImplicitParams({
    @ApiImplicitParam(
        required = true,
        dataType = "com.example.SomeObjectDto",
        paramType = "body"
    )
})

但通常情况下，如果您只需在方法签名上添加 class，它就会起作用。

private Object retrieveByName(SomeObjectDto someObjectDto) {
    someCode();
}

SomeObjectDto class 还应该包含 "get" 变量的方法，例如。

class SomeObjectDto {
    private String info;

    getInfo(){
        return info;
    }
}

将产生以下 JSon.

{ info: "string" }

Answer 2

ApiImplicitParam 可以将参数映射到正确的类型，但类型必须由 swagger 检测，因此必须是有效的引用。我能让这个工作的唯一方法是使用 additionalModels 方法。

spring-boot 中的示例：
配置 swagger

import springfox.documentation.spring.web.plugins.Docket;
import com.fasterxml.classmate.TypeResolver;
...

@Bean
public Docket api(TypeResolver typeResolver) {
  return new Docket(DocumentationType.SWAGGER_2)
    .groupName("your-group-rest-api")
    .select()
    .apis(RequestHandlerSelectors.basePackage("your.package"))
    .paths(PathSelectors.any())
    .build()
    .additionalModels(typeResolver.resolve(YourModel.class))
    .apiInfo(apiInfo());
}

控制器

@ApiOperation...
@ApiImplicitParams(
  @ApiImplicitParam(dataType = "YourModel", name = "requestJson", paramType = "body"))
@ApiResponses...
@RequestMapping...
public void yourMethod(@RequestBody String requestJson,...)

当然，您可以为请求设置一个 InputStream 参数并将其映射到您的模型。

Swagger 数据类型不生成文档

Swagger datatype not generating docs

java

swagger

spark-java

microservices