Swagger是什么？
官方说法：Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
个人觉得，swagger的一个最大的优点是能实时同步api与文档。在项目开发过程中，发生过多次：修改代码但是没有更新文档，前端还是按照老旧的文档进行开发，在联调过程中才发现问题的情况（当然依据开闭原则，对接口的修改是不允许的，但是在项目不稳定阶段，这种情况很难避免）。
一、开发环境
1、idea 2018
2、springboot2.0.2.RELEASE
3、Java 1.8
二、编写一个简单的springboot 项目， 网上有很多小例子，下面是我自己写的一个小demo， 代码就直接贴出来，比较简单
1、目录结构
2、User
/**
* Description:
* User: wyt
* Date: 2018-05-28 10:31
*/
@Entity
public class User {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Integer id;
@Column
private String name;
@Column
private Integer age;
public Integer getId() {
return id;
}
public void setId(Integer id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
}3、UserRepository
/**
* Description:
* User: wyt
* Date: 2018-05-28-10:34
*/
public interface UserRepository extends JpaRepository<User, Integer> {
}4、UserController
/**
* Description:
* User: wyt
* Date: 2018-05-28 10:18
*/
@RestController
public class UserController {
@Autowired
UserRepository userRepository;
@GetMapping("/simple/{id}")
public User findById(@PathVariable Integer id) {
return this.userRepository.findById(id).orElse(null);
}
}5、application.yml
server:
port: 8088
spring:
profiles:
active: prod
datasource:
driver-class-name: com.mysql.jdbc.Driver
url: jdbc:mysql://localhost:3306/dbdemo?useUnicode=true&characterEncoding=utf-8&useSSL=false
username: root
password: 12345
jpa:
hibernate:
ddl-auto: none
show-sql: true
generate-ddl: false
logging:
level:
root: INFO
org.hibernate: INFO
org.hibernate.type.descriptor.sql.BasicBinder: TRACE
org.hibernate.type.descriptor.sql.BasicExtractor: TRACE
com.itmuch: DEBUG
6、pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.wyt</groupId>
<artifactId>spring-boot-swagger-test</artifactId>
<version>0.0.1-SNAPSHOT</version>
<packaging>jar</packaging>
<name>spring-boot-swagger-test</name>
<description>Demo project for Spring Boot</description>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.0.2.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<java.version>1.8</java.version>
</properties>
<repositories><!-- 代码库 -->
<repository>
<id>maven-ali</id>
<url>http://maven.aliyun.com/nexus/content/groups/public//</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</snapshots>
</repository>
</repositories>
<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-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-aop</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
7、user数据表字段
以下介绍 swagger ui和spring boot集成生成api文档
三、pom.xml添加swagger 相关依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>四、创建Swagger2配置类
/**
* Description:
* User: wyt
* Date: 2018-05-28-10:51
*/
/**
* Swagger2配置类
* 在与spring boot集成时，放在与Application.java同级的目录下。
* 通过@Configuration注解，让Spring来加载该类配置。
* 再通过@EnableSwagger2注解来启用Swagger2。
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
* 本例采用指定扫描的包路径来定义指定要建立API的目录。
*
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.wyt.demo.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 创建该API的基本信息（这些基本信息会展现在文档页面中）
* 访问地址：http://项目实际地址/swagger-ui.html
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot 中使用Swagger2构建RESTful APIs")
.description("api根地址：http://localhost:8088")
.termsOfServiceUrl("http://localhost:8088")
.contact("wyt")
.version("1.0")
.build();
}
}如上代码所示，通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。
五、相关注解解读
Swagger使用的注解及其说明：
@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
l code：数字，例如400
l message：信息，例如"请求参数没填好"
l response：抛出异常的类
@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
l @ApiModelProperty：描述一个model的属性
注意：@ApiImplicitParam的参数说明：
paramType：指定参数放在哪个地方
header：请求参数放置于Request Header，使用@RequestHeader获取
query：请求参数放置于请求地址，使用@RequestParam获取
path：（用于restful接口）–>请求参数的获取：@PathVariable
body：（不常用）
form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传 true | false
value：说明参数的意思
defaultValue：参数的默认值
例子： DemoController.java
/**
* Description:
* 一个用来测试swagger注解的控制器
* 注意@ApiImplicitParam的使用会影响程序运行，如果使用不当可能造成控制器收不到消息
* User: wyt
* Date: 2018-05-28-10:59
*/
@Controller
@RequestMapping("/demo")
@Api(value = "DemoController|一个用来测试swagger注解的控制器")
public class DemoController {
@Autowired
UserRepository userRepository;
@ResponseBody
@GetMapping("/getName")
@ApiOperation(value = "根据用户编号获取用户姓名", notes = "test: 根据id获取用户名")
@ApiImplicitParam(paramType = "query", name = "id", value = "用户编号", required = true, dataType = "Integer")
public String getName(@RequestParam Integer id) {
return this.userRepository.findById(id).orElse(null).getName();
}
}完成上述代码添加上，启动Spring Boot程序，访问：http://localhost:8088/swagger-ui.html
