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>
史上最简单最全面三步生成 swagger API 离线markdown/html文件
最新推荐文章于 2024-08-18 10:15:38 发布