springboot整合swagger（api集成、转word、离线文档）

ゝ一纸荒年。 2022-10-07 01:00 179阅读 0赞

网络上有许多零零散散的swagger相关使用说明，这里整合如下参考内容及个人过程中发现和解决的相关问题：

1.相关pom依赖【**注意点：不同版本swagger-ui不同，依赖包版本不同会出现类似方法找不到，包依赖报错问题**】

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>${springfox-version}</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>${springfox-version}</version>
            </dependency>
            
            <dependency>
                <groupId>com.google.guava</groupId>
                <artifactId>guava</artifactId>
                <version>28.0-jre</version>
            </dependency>
    
            
            <dependency>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup</artifactId>
                <version>1.3.3</version>
            </dependency>
            
            <dependency>
                <groupId>ch.netzwerg</groupId>
                <artifactId>paleo-core</artifactId>
                <version>0.11.0</version>
            </dependency>
            <dependency>
                <groupId>nl.jworks.markdown_to_asciidoc</groupId>
                <artifactId>markdown_to_asciidoc</artifactId>
                <version>1.0</version>
            </dependency>
            
            <dependency>
                <groupId>io.swagger</groupId>
                <artifactId>swagger-core</artifactId>
                <version>1.5.21</version>
            </dependency>
    
            
            <dependency>
                <groupId>io.swagger</groupId>
                <artifactId>swagger-models</artifactId>
                <version>1.5.21</version>
            </dependency>

2.swaggerConfig-配置文件：

@EnableSwagger2--可加在启动类上看个人使用

/**
     * @author ：hw
     * @date ：Created in 2021/6/10
     * @modified By：
     * @version: 1.0.0
     */
    @Configuration
    @EnableSwagger2
    //@Profile({"2"})---设置环境对应使用权限
    public class SwaggerConfig {
        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    //是否开启 (true 开启  false隐藏。生产环境建议隐藏)
                    //.enable(false)
                    .select()
                    //扫描的路径包,设置basePackage会将包下的所有被@Api标记类的所有方法作为api
                    .apis(RequestHandlerSelectors.basePackage("org.word.controller"))
                    //指定路径处理PathSelectors.any()代表所有的路径
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    //设置文档标题(API名称)
                    .title("SpringBoot-Swagger2")
                    //文档描述
                    .description("接口说明")
                    //服务条款URL
                    .termsOfServiceUrl("http://localhost:8080/")
                    //版本号
                    .version("1.0.0")
                    .build();
        }
    
    
    }

3.项目启动，访问swagger-UI对应界面：http://localhost:8080/swagger-ui.html

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4MDMzMjM5_size_16_color_FFFFFF_t_70][]

两个重要的URL：

UI访问：http://localhost:8080/swagger-ui.html

对应文档：http://localhost:8080/v2/api-docs

可以替代直接使用报文或者对应的请求发起接口测试，如下图

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4MDMzMjM5_size_16_color_FFFFFF_t_70 1][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4MDMzMjM5_size_16_color_FFFFFF_t_70 2][]

4.生成对应的api文档，一定要保证pom依赖正确（上面pom文件已经包含）-关键依赖：

<dependency>  
            <groupId>io.github.swagger2markup</groupId>  
            <artifactId>swagger2markup</artifactId>  
            <version>1.3.3</version>  
        </dependency>

生成-直接run对应方法即可：

/**
     * @author ：hw
     * @date ：Created in 2021/6/10
     * @modified By：
     * @version: 1.0.0
     */
    @RunWith(SpringRunner.class)
    @SpringBootTest(classes = Application.class)
    public class Swagger2MarkUpTest {
        /**
         * 生成Markdown格式文档,并汇总成一个文件
         *
         * @throws Exception
         */
        @Test
        public void generateMarkdownDocsToFile() throws Exception {
            //  输出Markdown到单文件
            Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                    .withMarkupLanguage(MarkupLanguage.MARKDOWN)
                    .withOutputLanguage(Language.ZH)
                    .withPathsGroupedBy(GroupBy.TAGS)
                    .withGeneratedExamples()
                    .withoutInlineSchema()
                    .build();
    
            Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                    .withConfig(config)
                    .build()
                    .toFile(Paths.get("./docs/api"));
        }
    }

5.swagger本身是不支持生成word文档，需要对应模板，将http://localhost:8080/v2/api-docs返回的api接口的相关信息json串转化成word文档；

这里提供：[https://gitee.com/yellowill/SwaggerSpringBoot.git][https_gitee.com_yellowill_SwaggerSpringBoot.git]\--参考

使用：![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4MDMzMjM5_size_16_color_FFFFFF_t_70 3][]

参考内容如下：

[swagger-ui导出word接口文档\_a116385895的博客-CSDN博客][swagger-ui_word_a116385895_-CSDN]

[Swagger2生成接口文档\_gaochenglong1的博客-CSDN博客\_swagger2生成接口文档][Swagger2_gaochenglong1_-CSDN_swagger2]

[使用Swagger2Markup导出swagger2文档\_qq\_35140272的博客-CSDN博客][Swagger2Markup_swagger2_qq_35140272_-CSDN]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4MDMzMjM5_size_16_color_FFFFFF_t_70]: /images/20221005/1462188b1525456ba3f19124516ff361.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4MDMzMjM5_size_16_color_FFFFFF_t_70 1]: /images/20221005/1df6f1a21d77453894ddd29397db6eed.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4MDMzMjM5_size_16_color_FFFFFF_t_70 2]: /images/20221005/2d8740426e3149eab4015ccda147ac79.png
[https_gitee.com_yellowill_SwaggerSpringBoot.git]: https://gitee.com/yellowill/SwaggerSpringBoot.git
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4MDMzMjM5_size_16_color_FFFFFF_t_70 3]: /images/20221005/ef09bb297a8442fb95ff6090efc748f9.png
[swagger-ui_word_a116385895_-CSDN]: https://blog.csdn.net/a116385895/article/details/108405898?ops_request_misc=%257B%2522request%255Fid%2522%253A%2522162303843716780262522249%2522%252C%2522scm%2522%253A%252220140713.130102334..%2522%257D&request_id=162303843716780262522249&biz_id=0&utm_medium=distribute.pc_search_result.none-task-blog-2~all~baidu_landing_v2~default-7-108405898.first_rank_v2_pc_rank_v29&utm_term=swagger%E7%94%9F%E6%88%90word&spm=1018.2226.3001.4187
[Swagger2_gaochenglong1_-CSDN_swagger2]: https://blog.csdn.net/gaochenglong1/article/details/107257125/
[Swagger2Markup_swagger2_qq_35140272_-CSDN]: https://blog.csdn.net/qq_35140272/article/details/91451604?ops_request_misc=%257B%2522request%255Fid%2522%253A%2522162280269116780265457237%2522%252C%2522scm%2522%253A%252220140713.130102334..%2522%257D&request_id=162280269116780265457237&biz_id=0&utm_medium=distribute.pc_search_result.none-task-blog-2~all~sobaiduend~default-4-91451604.first_rank_v2_pc_rank_v29&utm_term=swagger2markup&spm=1018.2226.3001.4187