IDE下的springboot学习笔记(7)------swagger2的使用以及API多种方式导出
文章目录
- 前言
- swagger2
-
- 环境搭建
- swagger2使用
- swagger2markup
-
- Markdown、Confluence、AsciiDocs三种格式导出
- Html格式导出
- 总结
前言
在如今的开发中接口文档的编写是不可避免的，这是非常耗时的同时也存在很多局限性，如容易出现纰漏、不断的更新等等。今天给大家介绍一款API接口文档生成工具：swagger2，它可以动态的生成API接口文档。然后再使用swagger2markup来导出生成离线的API文档
swagger2
环境搭建
首先要准备一个springboot的环境，这里就不再介绍了，需要的可以看第一篇环境搭建，然后在pom.xml导入swagger2的依赖
pom.xml如下
<!--swagger2-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger-ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
然后再准备一个配置文件SwaggerConfig如下：
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 是否启用swagger文档，这个可以在application.yml中配置
*/
@Value("${swagger.enable}")
private boolean enable;
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.enable(enable)
.apiInfo(apiInfo())
.select()
// 这里配置要扫描的包,接口在哪个包就配置哪个包
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 这里配置的网页相关信息，具体不多介绍
* @return
*/
public ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("Springboot+swagger Demo")
.description("一个使用springboot整合swagger的例子")
.contact(new Contact("Colins~ ", "", "xxxxx"))
.version("1.0")
.build();
}
}
最后在application.yml中启用swagger2文档，如：
接下来就可以运行项目，然后浏览器打开http://localhost:8080/swagger-ui.html这个地址查看了，这里由于controller层还没有接口所以没内容
接下来写几个接口看看swagger2如何使用吧
swagger2使用
ps：这里关于swagger2的注解并没有介绍全，同时也不完整详情使用见：
https://gumutianqi1.gitbooks.io/specification-doc/content/tools-doc/spring-boot-swagger2-guide.html
controller接口层
@Api(tags = "用户接口")//对Controller的描述
@Controller
public class UserController
{
@Autowired
private UserMapper userMapper;
@ResponseBody
@ApiOperation("查询用户及爱好")//对接口的描述
//请求类型最好是确定用什么请求方式 不然它会列举所有请求方式出来 ps：这里没有确定 下面的确定了 对比看看效果
@RequestMapping(value = "/more")
public List<User> more(){//这里返回类型是实体类 详情见实体类配置 传参如果是实体类也是一样的
List<User> users = userMapper.queryMoreData();//一个数据库的查询操作，这个可自己编写
return users;
}
@ApiOperation(value = "测试接口", notes = "此接口描述")//对接口的描述
@ApiImplicitParams({//对传参的描述 多个参数就有多个@ApiImplicitParam用，隔开
@ApiImplicitParam(name = "id", value = "用户ID", required = false)
})
@GetMapping(value = "/test")
public String test(String id){
return id;
}
}
user实体类
@Data
@ApiModel//实体类声明
public class User {
@ApiModelProperty("用户id")//参数描述
private Integer id;
@ApiModelProperty("用户名字")//参数描述
private String name;
@ApiModelProperty("用户性别")//参数描述
private String sex;
@ApiModelProperty("用户年龄")//参数描述
private Integer age;
@ApiModelProperty("用户城市")//参数描述
private String city;
@ApiModelProperty("用户地址")//参数描述
private String address;
@ApiModelProperty("用户创建时间")//参数描述
private Date createTime;
@ApiModelProperty("用户更新时间")//参数描述
private Date updateTime;
@ApiModelProperty("用户图片路径")//参数描述
private String picUrl;
}
重新运行项目看看效果，一个controller一个实体对应着都出来了
为什么两个接口会出来这么多接口呢？这主要是第一个接口没有确定请求方式，所以这里全部列举出来了
关于实体类的描述下面也全有了
点击相应接口即可以在线调试，而且传参和返回值都有相应描述
以上则是在线的API文档，那怎么导出来变成离线的API文档呢？下面让我们来用swagger2markup实现文档导出
swagger2markup
Markdown、Confluence、AsciiDocs三种格式导出
导出功能参考了：http://www.spring4all.com/article/699
由于用到了swagger2markup所以要导入相关依赖
pom.xml
<!-- https://mvnrepository.com/artifact/nl.jworks.markdown_to_asciidoc/markdown_to_asciidoc -->
<dependency>
<groupId>nl.jworks.markdown_to_asciidoc</groupId>
<artifactId>markdown_to_asciidoc</artifactId>
<version>1.1</version>
</dependency>
<!--swagger2markup-->
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.1</version>
</dependency>
这里需要注意了，asciidoc这个依赖在maven默认的源库里是找不到的所以我们需要把maven的源换成阿里云的，在.m2文件夹下的setting.xml中加入
<mirrors>
<mirror>
<id>nexus-aliyun</id>
<mirrorOf>*</mirrorOf>
<name>Nexus aliyun</name>
<url>https://maven.aliyun.com/repository/jcenter</url>
</mirror>
</mirrors>
如果没有setting.xml文件就自己新建一个，然后加入如下内容：
<settings>
<localRepository>这里换成自己repository文件夹的路径</localRepository>
<mirrors>
<mirror>
<id>nexus-aliyun</id>
<mirrorOf>*</mirrorOf>
<name>Nexus aliyun</name>
<url>https://maven.aliyun.com/repository/jcenter</url>
</mirror>
</mirrors>
</settings>
然后在IDE中引用刚新建的setting文件
最后在springboot中的Test类中添加如下内容：
/**
* 生成AsciiDocs格式文档
* @throws Exception
*/
@Test
public void generateAsciiDocs() throws Exception {
// 输出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))//线上网页上的Title下的一个路径，我上面介绍的时候有标记
.withConfig(config)
.build()
.toFolder(Paths.get("./docs/asciidoc/generated"));//生成文档的路径
}
/**
* 生成Markdown格式文档
* @throws Exception
*/
@Test
public void generateMarkdownDocs() 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()
.toFolder(Paths.get("./docs/markdown/generated"));
}
/**
* 生成Confluence格式文档
* @throws Exception
*/
@Test
public void generateConfluenceDocs() throws Exception {
// 输出Confluence使用的格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("./docs/confluence/generated"));
}
/**
* 生成AsciiDocs格式文档,并汇总成一个文件
* @throws Exception
*/
@Test
public void generateAsciiDocsToFile() throws Exception {
// 输出Ascii到单文件
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.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/asciidoc/generated/all"));
}
/**
* 生成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/markdown/generated/all"));
}
这时就可以自己根据需求来运行这些测试类生成文档了
看到Html没，这玩意得导入一个插件才能生成
Html格式导出
pom.xml中加入插件
<!--生成html插件-->
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<!--现在asciidoc文档路径-->
<sourceDirectory>./docs/asciidoc/generated</sourceDirectory>
<!--生成html文件路径-->
<headerFooter>true</headerFooter>
<doctype>book</doctype>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<!--菜单栏在左边-->
<toc>left</toc>
<!--多标题排列-->
<toclevels>3</toclevels>
<!--自动打数字序号-->
<sectnums>true</sectnums>
</attributes>
</configuration>
</plugin>
然后加入一个新的maven命令
最后运行这个命令就好了
接着那个html就出来了，打开就是这样
总结
这样关于swagger2的动态API文档就搞定啦，是不是很简单，文中若有不足或有错的请指出，多多包涵