Swagger 2 (Spring fox) 在我的 API 中添加了“es”

Question

我只是想将 Swagger 集成到我用 Gradle 构建的 Spring Boot (JAX-RS) 项目中。我能够生成与以下相同的泊坞窗（Swagger UI）：

我已经使用默认设置配置了我的招摇：

package com.abc;

import lombok.extern.slf4j.Slf4j;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Import;
import org.springframework.data.mongodb.repository.config.EnableMongoRepositories;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableAutoConfiguration
@SpringBootApplication
@EnableMongoRepositories
@Slf4j
@Import({springfox.documentation.spring.data.rest.configuration.SpringDataRestConfiguration.class,springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration.class})
@EnableSwagger2
public class ServiceApplication {

    public static void main(String[] args) {
        SpringApplication.run(ServiceApplication.class, args);
    }

    public static void run(String[] args) throws Exception{
        log.info("Started application on: 8080");
    }
}

正如我们在 GET Events API 的图像中看到的，泊坞窗显示 /eventses .. 所以它从哪里添加 es 到 /events API，写成：

@GET
public HashMap<String, Object> getEventList(@DefaultValue("1") @QueryParam("page") int page,
        @DefaultValue("10") @QueryParam("rpp") int rpp, @QueryParam("events") String eventIds) {
    HashMap<String, Object> eventsResultMap= new HashMap<String, Object>();

    List<Events> events = null;

    if (eventIds != null && eventIds.length() > 0) {
        List<String> eventsIdList = Arrays.asList(eventIds.split(","));
        log.info("" + eventsIdList);
        events = eventService.getEvents(eventsIdList);
    } else {
        events = eventService.getEvents(page - 1, rpp);
    }
    eventsResultMap.put("EVENTS", events);

    HashMap<String, Object> recordsMetaMap = new HashMap<String, Object>();
    recordsMetaMap.put("total", eventService.totalCount());
    recordsMetaMap.put("page", page);
    recordsMetaMap.put("rpp", rpp);
    eventsResultMap.put("_metadata", recordsMetaMap);
    log.info("The events you have queried for are:" + eventsResultMap);
    return eventsResultMap;
}

请指导我哪里做错了。需要做哪些自定义配置。

我从 spring 官方文档中获取了Reference。

Answer 1

/eventses 中的所有内容均来自 Springfox 对 Spring Data REST 的支持，与控制器中的 getEventList 方法无关。如果您不想像这样自动发现您的实体，那么从 @Import 行中删除该类应该可以解决问题。

Answer 2

如果你在 spring boot 中使用 jax-rs 实现，你应该使用 swagger-core jax-rs 库而不是 spring fox。 Swagger 团队提供了非常详细的说明 here 关于如何为不同的实现（如 jersey、rest-easy 等）配置您的应用程序。我发现它很容易集成到 jersey 2.x 中。

为了使您的 swagger 文档更加丰富，您应该尝试使用不同的 swagger 注释提供尽可能多的元数据，如文档中的 here。 Swagger 在某些情况下（例如 QueryParam 与 PathParam 标识）充分利用了这些注释与 jax-rs 注释相结合。

如果您让我知道您使用的是哪个 jax-rs 实现，我或许可以为您提供一些示例配置。

编辑：

对于 Jersey 2.x，您需要在 Jersey 配置类中添加类似这样的内容（扩展 org.glassfish.jersey.server.ResourceConfig）：

@Bean
public BeanConfig swaggerConfig() {

    register(ApiListingResource.class);
    register(SwaggerSerializers.class);

    BeanConfig config = new BeanConfig();
    config.setConfigId("your-config-id");
    config.setTitle( "Your Title" );
    config.setSchemes(new String[] { "https", "http" });
    config.setBasePath("your application base path E.g. /api");
    config.setResourcePackage("package to be scanned E.g. com.example");
    config.setPrettyPrint(true);
    config.setScan(true);
    return config;
}

除此之外，您还需要使用大张旗鼓的注释来注释您的端点（服务）类。例如。

@Path("/material")
@Service
@Api(value = "Material")
public class MaterialEndpoint {

    @POST
    @ApiOperation(value = "Create Material")
    @ApiResponses(value = { @ApiResponse(code = 201, message = "Success", response = CreateMaterialResponse.class),
                            @ApiResponse(code = 409, message = "Failure", response = ErrorResponse.class) })
    public Response createMaterial(CreateMaterialRequest createMaterialRequest){
// Code goes here
   }

}

还有带有大张旗鼓注释的实体。您希望自己的 swagger 文档有多丰富，这取决于您。根据具体情况，您可以选择注释更多或更少的类。