史上最简单最全面三步生成 swagger API 离线markdown/html文件

GitHub地址链接见文章底部!

前提:
你的 Controller 都已经加上了 swagger 的 API 注解

步骤:

1. 下载 : 下载或 clone 此项目,运行 maven 的 install 命令将本项目安装到 maven 库 

           github链接:https://github.com/zylwendao/swagger-api

2. 配置 : 你的项目不用添加任何 swagger 的依赖,(如果不想将我的这个 API 生成项目嵌入你的项目,想        
         用完一次生成 API 文档就拉倒,
         你可以先注释掉你自己项目 pom 的 swagger 依赖,暂时先用我的这个,
         用完了再删掉我的 maven 坐标,恢复你自己pom 里面的 swagger 依赖)
         只需要将此项目的 maven 坐标(如下)引入你项目的 pom 依赖,并且在你的项目的启动类上加入 
         扫描地址 "swagger"
	maven 坐标:
	<dependency>
		<groupId>org.example</groupId>
		<artifactId>swagger-api</artifactId>
		<version>1.0-SNAPSHOT</version>
	</dependency>

	SpringBoot 启动类注解(添加下面这 2 个就够了):
		@EnableSwagger2Doc
		@ComponentScan(basePackages={"com.xxx你的项目扫描地址","swagger"})
		
3. 运行 : 
      生成 markdown 类型文件 : 新建一个 Controller(如下) ,运行工具类,你就可以在你的 Resourses 文件夹下面看到新生产的 doc 文件夹,
      如果看不见就鼠标右键点击 resoueces 文件夹选择 - Reload from disk - 功能刷新一下;
                             
              @RestController
              public class MakeApi {
                  @Autowired
                  MakeSwaggerApiUtil makeSwaggerApiUtil;

                  @RequestMapping("make")
                  public String run(){
                      return makeSwaggerApiUtil.makeAPI();
                  }
              }
              
              调用工具链接 : http://localhost:8080(注意修改成你的端口)/make; 
	      执行成功 : 返回 success
              
	      在线查看 API 地址 : http://localhost:8080/swagger-ui.html
                             
      生成 html 类型文件 : 必需先执行一次上面的 controller(因为要用到这个 controller 生成的 asciidoc.adoc文件),
      			然后在你的 pom 的 <build> 标签的<plugins> 里面加入下面的打包工具,
			然后在你 IDEA 边栏的 maven 的 plugins 里面找到 asciidoctor -> asciidoctor:process-asciidoc ,
			找到以后鼠标右键选择 Run Maven Build ,搞定! 
			resources 里面就会生成 docs 文件夹,这里面就会有 html 接口文件,没有就刷新一下,如何刷新,如上. 
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.6</version>
                <configuration>
                    <!--asciidoc文件目录-->
                    <sourceDirectory>src/main/resources/docs</sourceDirectory>
                    <!---生成html的路径-->
                    <outputDirectory>src/main/resources/html</outputDirectory>
                    <backend>html</backend>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <attributes>
                        <!--导航栏在左-->
                        <toc>left</toc>
                        <!--显示层级数-->
                        <!--<toclevels>3</toclevels>-->
                        <!--自动打数字序号-->
                        <sectnums>true</sectnums>
                    </attributes>
                </configuration>
            </plugin>
            
 自定义配置: 
 swagger 想要配置文档信息的话,可以在你项目的 application.yml 文件里面加入配置,这里只举例一个 title,其他的可以自行百度.
 swagger:
  enabled: true
  title: "我是 title"
  
 采坑经验:
 出现异常 : java.lang.NumberFormatException: For input string: "",这个不用管,是 swagger 的数字转换异常,是 swagger 插件的 bug,不影响程序运行.
 
 冲突:
    下面这两个 pom 依赖需要暂时注释掉 ( 如果你的项目有用到的话 ) ,不然会报异常,导致不能正常运行 swagger
        
	
		<dependency>
			<groupId>org.owasp.esapi</groupId>
			<artifactId>esapi</artifactId>
			<version>2.1.0</version>
		</dependency>
		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-databind</artifactId>
			<version>2.9.9.1</version>
		</dependency>