swagger静态文档生成

最新推荐文章于 2024-08-28 17:14:55 发布

withingwolf

最新推荐文章于 2024-08-28 17:14:55 发布

阅读量3.2k

点赞数

分类专栏： java 文章标签： java swagger api文档 swagger静态文档生成

本文链接：https://blog.csdn.net/asd765028286/article/details/84967220

版权

本文档介绍了如何使用springfox-staticdocs组件从swagger动态文档生成静态HTML和PDF文档，解决在未部署或内网环境下的接口文档分享问题。通过修改maven插件配置，可以解决PDF中文显示不正确的问题。

摘要由CSDN通过智能技术生成

swagger静态文档生成

有时候给接口文档的时候不能直接给个URL,这可能因为没部署上服务器,亦或是内网的限制.

这时对方需要一个HTML或者是个PDF静态文档,本来想着在swagger网址那里Ctrl+S保存下来发过去就行了,结果这样保存的文档根本不能看.

调研后发现,可以通过springfox-staticdocs组件生成swagger静态文件,然后通过maven组件根据静态文件生成HTML和PDF.

以之前的swagger示例项目来展示.
swagger接入请看 withing

话不多说上代码

首先添加dependency依赖

 <properties>
        <swagger.version>2.6.1</swagger.version>

        <!--生成静态文档所需属性-->
        <start-class>com.f6car.base.Application</start-class>
        <snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
    <asciidoctor.input.directory>${project.basedir}/docs/asciidoc</asciidoctor.input.directory>
        <generated.asciidoc.directory>${project.build.directory}/asciidoc</generated.asciidoc.directory>
        <asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
        <asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
    </properties>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-staticdocs</artifactId>
    <version>${swagger.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-test</artifactId>
    <version>2.0.0.RELEASE</version>
    <scope>test</scope>
</dependency>

这里有个坑要注意: swagger.version换成2.6.1了,这是因为springfox-staticdocs这个组件只支持到2.6.1,但不能将其他两个swagger2和swagger-ui版本换成2.8.x或2.7.x,因为springfox-staticdocs生成文档时会调用以前版本的某个函数,更换成新版本会抛出MethodNotFoundException

添加测试用例生成swagger静态文件

@RunWith(SpringRunner.class)
@SpringBootTest
public class SwaggerStaticDocTest {
   
    @Autowired
    private WebApplicationContext context;
    private String snippetDir = "target/generated-snippets";
    private String outputDir = "target/asciidoc";

    private MockMvc mockMvc;

    @Before
    public void setUp() {
   
        this.mockMvc = MockMvcBuilders.webAppContextSetup(this