Swagger 2（Spring fox）将'es'添加到我的API中

Question

我只是尝试将 Swagger 集成到使用Gradle构建的 Spring Boot（JAX-RS） 项目中。我能够生成docker（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 事件API ，docker显示/ 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;
}

请指导我做错的地方。需要做哪些自定义配置。

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

Answer 1

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

Answer 2

如果你使用带有spring boot的jax-rs实现，你应该使用swagger-core jax-rs库而不是spring fox。 Swagger团队提供了非常详细的说明here，说明如何为不同的实施方案配置您的应用程序，如球衣，休息等。我发现很容易整合为球衣2.x.

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

如果您让我知道您正在使用哪种jax-rs实现，我可能会为您提供一些示例配置。

修改

对于Jersey 2.x，您需要在Jersey Configuration类中添加类似的内容（扩展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;
}

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

@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
   }

}

你的实体带着招摇的注释。你希望你的招摇文档有多丰富，这取决于你。根据您的不同，您可以选择注释更多或更少的类。