Swagger 2 (Spring fox) 将 'es' 添加到我的 API

Question

我只是想将 Swagger 集成到我的 Spring 引导 (JAX-RS) 使用 Gradle.I 构建的项目能够生成一个 docker (Swagger UI) 与以下相同：

我已经使用默认设置配置了 swagger，如下所示：

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

请指导我我在做什么wrong.What需要完成自定义配置。

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

Answer 1

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

Answer 2

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

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

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

编辑：

对于 Jersey 2.x，您需要在 Jersey 配置 class（扩展 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 注释来注释您的端点（服务）classes。例如。

@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 注释的实体。您希望自己的 swagger 文档有多丰富取决于您。根据这一点，您可以选择或多或少地注释 classes.

Swagger 2 (Spring fox) 将 'es' 添加到我的 API

Swagger 2 (Spring fox) adds 'es' to my API's

spring

jax-rs

swagger-ui

spring-boot

swagger-2.0