springboot 2.2.7集成Swagger 2.9.2并生成markdown格式API文档Demo

1.关键操作

• 添加依赖

 <!--        swagger2 依赖开始-->
        <!--  https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-annotations</artifactId>
                </exclusion>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <!-- 解决进入swagger页面报类型转换错误，排除2.9.2中的引用，手动增加1.5.21以上版本，这里选1.6.0版本-->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.6.0</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.swagger/swagger-models -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.6.0</version>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.swagger/swagger-core -->
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-core</artifactId>
            <version>1.6.0</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

        <!--swagger2markup用的到-->
        <!-- https://mvnrepository.com/artifact/org.pegdown/pegdown -->
        <dependency>
            <groupId>org.pegdown</groupId>
            <artifactId>pegdown</artifactId>
            <version>1.6.0</version>
            <scope>test</scope>
        </dependency>
        <!-- https://mvnrepository.com/artifact/io.github.swagger2markup/swagger2markup
        可能有两个包无法自动导入，需要手工处理，见本文第7小节
        -->
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.3.3</version>
        </dependency>
        <!--        swagger2 依赖结束-->

• application.yml加入swagger开关

swagger:
  enable: true

• 编写配置类
  config/Swagger2Config.java

package com.example.swagger2.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author alexhu
 */
@EnableSwagger2
@Configuration
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    //构建 api文档的详细信息函数
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("功能测试")
                //创建人
                .contact(new Contact("Alex Hu", "www.example.com", "email@example.com"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }
}

• 控制器类加注解，关键@Api/@ApiOperation/@ApiParam三个
  controller/ExampleController.java

package com.example.swagger2.controller;

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author alexhu
 */
@Api(tags = "样例Controller",value = "控制器Demo")
@RestController
public class ExampleController {

    @ApiOperation(value = "回显name",httpMethod = "GET")
    @GetMapping("/echo/{name}")
    public String echoName(@ApiParam(name = "name", value = "名字", required = true) @PathVariable("name") String name) {
        return "Echo " + name;
    }

    @ApiOperation(value = "问候name",httpMethod = "GET")
    @GetMapping("/hello")
    public String helloName(@ApiParam(name = "name", value = "名字", required = true) @RequestParam("name") String name) {
        return "Hello " + name;
    }
}

• 编写测试代码，生成full-api-doc.md

package com.example.swagger2;

import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;

import java.net.URL;
import java.nio.file.Paths;

@RunWith(SpringRunner.class)
@SpringBootTest
public class SwaggerTo {
    /**
     * 生成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/full-api-doc"));
    }
}

• 启动项目，访问

http://localhost:8080/swagger-ui.html

2.常见问题–两个包无法导入

在这里 如果通过maven不能download这两个jar的同学可以去下载这两个jar
https://mvnrepository.com/artifact/nl.jworks.markdown_to_asciidoc/markdown_to_asciidoc/1.0
https://mvnrepository.com/artifact/ch.netzwerg/paleo-core/0.11.0
下载jar后本地安装到本地仓库：

mvn install:install-file -Dfile=~/Downloads/markdown_to_asciidoc-1.1.jar -DgroupId=nl.jworks.markdown_to_asciidoc -DartifactId=markdown_to_asciidoc -Dversion=1.0 -Dpackaging=jar
mvn install:install-file -Dfile=~/Downloads/paleo-core-0.14.0.jar -DgroupId=ch.netzwerg -DartifactId=paleo-core -Dversion=0.11.0 -Dpackaging=jar

脚本中是升级了，用新版本当旧版本用

3.参考链接

1. https://blog.csdn.net/qq_40592377/article/details/89520847
2. https://blog.csdn.net/jiangshuanshuan/article/details/84325692
3. https://www.freesion.com/article/8284174476/