首先我们需要先引入swagger相关依赖,然后使用@EnableSwagger2注解开启swagger
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.9.0.RELEASE</version>
</dependency>
其次我们需要引入生成文档需要的工具依赖,这里使用<scope>test</scope>可以避免该依赖被编译打包,在引入该依赖之前先配置一个仓库避免从maven官方下载该依赖失败。
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.3</version>
<scope>test</scope>
</dependency>
<repositories>
<repository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>jcenter-releases</id>
<name>jcenter</name>
<url>http://jcenter.bintray.com</url>
</repository>
</repositories>
下面我们通过junit测试实现Swagger静态文档的生成,代码参考如下:
@RunWith(SpringRunner.class)
@SpringBootTest
public class SwaggerApplicationTest {
@SneakyThrows
@Test
public void generateAsciiDocs(){
URL url = new URL("http://localhost:8001/v2/api-docs");
Path path = Paths.get("src/docs/asciidoc/generated");
//通过Swagger2MarkupConfigBuilder构造输出文档类型相关配置,此处选择ASCIIDOC类型文件
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder().withMarkupLanguage(MarkupLanguage.ASCIIDOC).build();
//通过Swagger2MarkupConverter执行最后转换,toFolder表示输出到文件夹,如果不想分开可以选择toFile直接输出到一个文件中
Swagger2MarkupConverter.from(url).withConfig(config).build().toFolder(path);
}
}
执行完该测试类之后,我们可以在src目录下看到生成的相关文件