Swagger 不显示/记录我的 RESTful 端点（JAX-RS，Spring-boot）

Question

我使用 Jax-RS 在 Java 和 Spring boot 开发了一个 RESTful 网络服务，我想用 Swagger 记录它。到目前为止，我已经成功地在 http:8080/localhost/<context>/swagger-ui.html 上映射了 swagger-ui.html 页面。 不幸的是，我的 RESTful 端点没有出现在任何地方。

我在用什么：

pom.xml

 <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>

Swagger 配置class

@Configuration
@EnableSwagger2
public class SwaggerConfiguration
{
    @Autowired
    private TypeResolver typeResolver;

    @Bean
    public Docket api()
    {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.nick.java.webservice.services"))
                .paths(PathSelectors.any())
                .build()
                .enable(true)
                .apiInfo(getApiInfo())
                .tags(
                        new Tag("My web service", "Methods for my RESTful service")
                );
    }

    private ApiInfo getApiInfo() {
        ApiInfo apiInfo = new ApiInfoBuilder()
                .title("API Documentation")
                .description("API")
                .version("1.0")
                .contact(new Contact("mycompany", "", "nickath@mycompany.com"))
                .build();

        return apiInfo;
    }

JAX-RS 端点示例

package org.nick.java.webservice.services;

@Path("/contextsapi")
@Consumes("application/json")
@Produces("application/json")
@Api(value = "Contexts API", produces = "application/json")
public interface ContextAPI {

    @Path("/contexts/contexts")
    @GET
    @ApiOperation( value = "get contexts",
                   response = List.class)
    List<Context> getContexts();

招摇-ui.html页面截图

如您所见，没有生成'get contexts'方法

知道我做错了什么吗？

======= 更新 - 服务实施 ========

package  org.nick.java.webservice.services.impl;
@Service
@Api(value = "Contexts Api Impl", produces = "application/json", description = "desc")
@Path("/contextsapi")
public class ContextAPIImpl implements ContextAPI {

   @Override
   @GET
   @ApiOperation( value = "get contexts", response = List.class)
   public List<Context> getContexts(){
     //code ommitted
   }
}

Answer 1

Swagger 假设不显示任何 API client 的文档。如果有任何带有 swagger 注释的服务，它将为您的服务生成文档。

要对此进行确认，请尝试创建一个 Spring @service 并使用 swagger 注释进行注释。如果所有其他方面都得到照顾，将生成该文档。由于您可以看到 UI，我认为依赖关系是正确的。

这里的想法是，您的任务是记录您的服务，swagger 可以帮助您完成这项工作。您没有责任为您的服务使用的 API(s) generate/publish 文档。由于您不维护服务，因此也没有必要维护文档。

我第一次使用Rest client的时候，也对这个有点疑惑。但仔细想想，这是意料之中的，也是有道理的。

Answer 2

已解决

最后，我按照此处 https://code.massoudafrashteh.com/spring-boot-cxf-jaxrs-hibernate-maven-swagger-ui/

中的示例使用 Swagger2Feature 设法解决了我的问题

Maven 依赖项

<cxf.version>3.1.15</cxf.version>
<swagger-ui.version>3.9.2</swagger-ui.version>

 <dependency>
        <groupId>org.apache.cxf</groupId>
        <artifactId>cxf-spring-boot-starter-jaxrs</artifactId>
        <version>${cxf.version}</version>
    </dependency>

    <dependency>
        <groupId>org.apache.cxf</groupId>
        <artifactId>cxf-rt-rs-service-description-swagger</artifactId>
        <version>${cxf.version}</version>
    </dependency>

    <dependency>
        <groupId>com.fasterxml.jackson.jaxrs</groupId>
        <artifactId>jackson-jaxrs-json-provider</artifactId>
        <version>${jackson.version}</version>
    </dependency>

    <dependency>
        <groupId>org.webjars</groupId>
        <artifactId>swagger-ui</artifactId>
        <version>${swagger-ui.version}</version>
    </dependency>

CxfConfig.java

@Configuration
public class CxfConfig {

@Autowired
private Bus bus;


@Bean
public Server rxServer(){
    final JAXRSServerFactoryBean endpoint = new JAXRSServerFactoryBean();
    endpoint.setProvider(new JacksonJsonProvider());
    endpoint.setBus(bus);
    endpoint.setAddress("/swagger");
    endpoint.setServiceBeans(Arrays.<Object>asList(contextAPI());
    Swagger2Feature swagger2Feature = new Swagger2Feature();
    endpoint.setFeatures(Arrays.asList(swagger2Feature));
    return endpoint.create();
}


@Bean
public ContextAPI contextAPI(){
    return new ContextAPIImpl();
}

现在可以在 http://localhost:8080///swagger/api-docs?url=//swagger/swagger.json

上获得 swagger 文档

要自定义端点的 UI 查看手册 here

Answer 3

我建议使用 Swagger 2 我遇到了同样的问题。问题出在您实施的 Docket 上，正确的正则表达式会有所帮助。示例：

@Configuration
@EnableSwagger2
public class SwaggerConfig {                                    
@Bean
public Docket api() { 
    return new Docket(DocumentationType.SWAGGER_2)  
      .select()                                  
      .apis(RequestHandlerSelectors.any())              
      .paths(PathSelectors.any())                          
      .build();                                           
}
}

可以参考上面的linkSetting up Swagger 2 Example Source code example也是来自上面的link.

Swagger 不显示/记录我的 RESTful 端点（JAX-RS，Spring-boot）

Swagger does not show / document my RESTful endpoints (JAX-RS, Spring-boot)

java

rest

jax-rs

swagger

spring-boot