Spring Boot - Spring Data REST 从存储库生成 swagger 文档

Question

我在 Spring Boot 中有一个带有 Spring Data Rest 的应用程序，我正在尝试使用 swagger-maven-plugin 使用 Swagger 生成文档。控制器文档生成没有问题，但存储库没有。

我在我的 pom.xml 中配置了如下形式的 swagger-maven-plugin：

                <plugin>
                <groupId>com.github.kongchen</groupId>
                <artifactId>swagger-maven-plugin</artifactId>
                <version>3.1.6</version>
                <configuration>
                    <apiSources>
                      <apiSource>
                            <springmvc>true</springmvc>
                            <locations>
                                <location>com.abelendo.repository</location>
                                <location>com.abelendo.controller</location>
                            </locations>
                            <schemes>http</schemes>
                            <host>localhost:8080</host>
                            <basePath>/</basePath>
                            <info>
                                <title>Swagger Maven Plugin Spring Boot for cars</title>
                                <version>v1</version>
                                <description>Working sample of Spring Boot for cars annotations</description>
                                <termsOfService>
                                    http://www.github.com
                                </termsOfService>
                                <contact>
                                    <email>abelendo@email.com</email>
                                    <name>Abelendo Cars</name>
                                    <url>http</url>
                                </contact>
                                <license>
                                    <url>http://www.license.com</url>
                                    <name>License name</name>
                                </license>
                            </info>
                            <!-- Support classpath or file absolute path here.
                            1) classpath e.g: "classpath:/markdown.hbs", "classpath:/templates/hello.html"
                            2) file e.g: "${basedir}/src/main/resources/markdown.hbs",
                                "${basedir}/src/main/resources/template/hello.html" -->
                            <templatePath>${basedir}/templates/strapdown.html.hbs</templatePath>
                            <outputPath>${basedir}/generated/document.html</outputPath>
                            <outputFormats>yaml</outputFormats>
                            <swaggerApiReader>com.github.kongchen.swagger.docgen.reader.SpringMvcApiReader</swaggerApiReader>
                            <swaggerDirectory>generated/swagger-ui</swaggerDirectory>
                        </apiSource>
                    </apiSources>
                </configuration>
                <executions>
                    <execution>
                        <phase>compile</phase>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

我的汽车存储库：

@Api(tags = "CarsRepo")
@RepositoryRestResource(path = "cars")
public interface CarRepository extends CrudRepository<Car, Long> {

<S extends Car> S save(@Valid S cars);

}

是否可以使用 swagger-maven-plugin 生成存储库文档？

Answer 1

要为 @RepositoryRestResource 生成 swagger 文档，您需要做的就是：

1. 在你的项目中拉取 io.springfox:springfox-data-rest 依赖
2. 在您的 swagger 配置类中导入 springfox.documentation.spring.data.rest.configuration.SpringDataRestConfiguration 类。

@Configuration
@EnableSwagger2
@Import(SpringDataRestConfiguration.class)
public class SwaggerConfig {

  @Bean
  public Docket api() { ... }

}

编辑：swagger 配置类不适用于 spring-boot 2.0、spring-data 2.0 和 spring-data-rest 3.0：swagger 中存在一个未解决的问题（链接到 swagger not being Java8 而 spring-boot 和 spring-data 是）。详情请看这里：https://github.com/springfox/springfox/issues/2298。

但是，我设法通过修补一些招摇的类来解决它。补丁背后的想法是使用 Java Optional 代替 Guava 和 Java 反射。修补的类是：

• springfox.documentation.spring.data.rest.EntityServicesProvider
• springfox.documentation.spring.data.rest.EntityContext
• springfox.documentation.spring.data.rest.EntityDeleteExtractor
• springfox.documentation.spring.data.rest.EntityFindAllExtractor
• springfox.documentation.spring.data.rest.EntityFindOneExtractor
• springfox.documentation.spring.data.rest.EntitySaveExtractor

Answer 2

我在 pom.xml 中只有 1 个依赖项

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-data-rest -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-data-rest</artifactId>
        <version>3.0.0</version>
    </dependency>

然后在Respository中导入@Import(SpringDataRestConfiguration.class)

它会生成文档