本篇文章主要介绍的是SpringBoot整合Swagger(API文档生成框架)和SpringBoot整合Actuator(项目监控)使用教程。
SpringBoot整合Swagger说明:如果想直接获取工程那么可以直接跳到底部,通过链接下载工程代码。
Swagger 介绍Swagger 是一套基于 OpenAPI 规范构建的开源工具,可以帮助我们设计、构建、记录以及使用 Rest API。Swagger 主要包含了以下三个部分:
Swagger Editor:基于浏览器的编辑器,我们可以使用它编写我们 OpenAPI 规范。
Swagger UI:它会将我们编写的 OpenAPI 规范呈现为交互式的 API 文档,后文我将使用浏览器来查看并且操作我们的 Rest API。
Swagger Codegen:它可以通过为 OpenAPI(以前称为 Swagger)规范定义的任何 API 生成服务器存根和客户端 SDK 来简化构建过程。
Swagger优缺点 优点易用性好,Swagger UI提供很好的API接口的UI界面,可以很方面的进行API接口的调用。
时效性和可维护性好,API文档随着代码变更而变更。 Swagger是根据注解来生成文API档的,我们可以在变更代码的时候顺便更改相应的注解即可。
易于测试,可以将文档规范导入相关的工具(例如 SoapUI), 这些工具将会为我们自动地创建自动化测试。
缺点重复利用性差,因为Swagger毕竟是网页打开,在进行接口测试的时候很多参数无法进行保存,因此不易于重复利用。
复杂的场景不易模拟,比如使用token鉴权的,可能每次都需要先模拟登录,再来进行接口调用。
不过上述的这些缺点其实也无伤大雅,可以配合Postman来一起使用!
Postman可以保存参数并持久化生成文件,也可以在Header中保存Token信息,也可以动态的生成数字签名等等。
如果有兴趣的话,可以看看我之前写的这篇文章。
地址: Postman使用教程
Swagger官网:
Swagger的GitHub地址:https://github.com/swagger-api
开发准备环境要求
JDK:1.8
SpringBoot:1.5.9.RELEASE
首先还是Maven的相关依赖:
pom.xml文件如下:
<properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> <java.version>1.8</java.version> <maven.compiler.source>1.8</maven.compiler.source> <maven.compiler.target>1.8</maven.compiler.target> </properties> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>1.5.9.RELEASE</version> <relativePath/> </parent> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-devtools</artifactId> <optional>true</optional> <scope>test</scope> </dependency> <!-- swagger RESTful API --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.2.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.2.2</version> </dependency> </dependencies>注: Swagger的jar包既可原生的 Swagger的架包,也可以选择maven仓库SpringBoot已经整合好的Swagger的架包。
application.properties的文件的配置和一般的SpringBoot项目一样即可。
代码编写SpringBoot使用Swagger其实很简单,只需要在启动的时候添加@EnableSwagger2注解开启,然后再使用@Bean注解初始化一些相应的配置即可,比如编辑Swagger UI界面的信息,指定Swagger负责扫描的package等等。
Swagger代码配置如下:
@Configuration @EnableSwagger2 public class Swagger2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.pancm")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2构建RESTful APIs") .description("测试") .termsOfServiceUrl("http://www.panchengming.com/") .contact("xuwujing") .version("1.0") .build(); } }因为Swagger主要是用于生成API文档,因此这里我们可以直接编写控制层的相关代码,忽略掉Service层和Dao层相关的代码编写。这里我们首先编写一个实体类。
实体类
又是万能的用户表
public class User { private Long id; private String name; private Integer age; //getter 和 setter 略 }Controller 控制层