SpringBoot整合Swagger2在线文档
我们前面有讲到说开发时会创建Restful风格的API接口，供第三方或前端人员使用，那么前端人员在使用的过程中怎么知道有哪些接口呢。这个时候可以通过写接口文档来解决，但不同的程序员写出来的可能不一样，前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。如果能有工具帮我们能规范接口文档，最好能自动帮我们生成接口文档就好了。于是生成在线文档的工具就是 swagger就产生了。
Swagger是一款开源工具，依据OpenAPI规范（OpenAPI Specification，简称OAS）可以帮助你设计，构建，生成文档，调用REST APIs。
1.号称世界上最流行的Api框架；
2.RestFul Api 文档在线自动生成工具，Api文档与Api定义同步更新（写完代码文档就实时更新）
3.可以直接运行，可以在线测试Api接口；
4.支持多种语言（java，php等）
Swagger工具既然这么好用，那么我们就来看一下在SpringBoot中怎么整合Swagger。
Swagger的工具很多，但SpringBoot中整合Swagger主要是使用Swagger来构建强大的Restful文档。也就是里面的Swagger UI工具。
这里我们用的版本是Swagger2。
选择web、 lombok、 mysql、spring data jpa 依赖 （也可以将spring data jpa 换成mybatis相关依赖）
项目创建成功后在pom文件中添加druid依赖包
完成后pom文件如下：
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<!--默认是8.*的版本，根据需要设置自己的版本号-->
<version>5.1.45</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>druid-spring-boot-starter</artifactId>
<version>1.1.10</version>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
添加数据库配置信息：
# 数据库的基本配置
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.url=jdbc:mysql://localhost:3306/boot1?characterEncoding=utf8&serverTimezone=GMT%2B8
#配置连接池
spring.datasource.type=com.alibaba.druid.pool.DruidDataSource
# JPA配置
spring.jpa.database=mysql
# 是否在控制台打印SQL
spring.jpa.show-sql=true
spring.jpa.hibernate.ddl-auto=update
# 指定默认的存储引擎为InnoDB，默认情况下，自动创建表的时候会使用 MyISAM 做表的引擎，
# 如果配置了数据库方言为 MySQL57Dialect，则使用 InnoDB 做表的引擎。
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL57Dialect
结构图如下：
User类：
package com.example.swagger.pojo;
import io.swagger.annotations.ApiModel;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import javax.persistence.*;
@Data
@NoArgsConstructor
@AllArgsConstructor
@Entity
@Table(name = "users")
public class User {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private int id;
private String uname;
private int age;
}
UserRepository类：
package com.example.swagger.dao;
import com.example.swagger.pojo.User;
import org.springframework.data.jpa.repository.JpaRepository;
public interface UserRepository extends JpaRepository<User,Integer> {
}
这里省略了service层，直接在控制层里调用dao层
userController类：
package com.example.swagger.controller;
import com.example.swagger.dao.UserRepository;
import com.example.swagger.pojo.User;
import com.example.swagger.util.Response;
import com.example.swagger.util.ResponseResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
@RestController
public class UserController {
@Autowired
private UserRepository userRepository;
//查询所有
@GetMapping("/users")
public ResponseResult<List<User>> selectUsers()
{
List<User> usersList= userRepository.findAll();
return Response.createOkResp(usersList);
}
//根据id查询
@GetMapping("/users/{id}")
public ResponseResult<User> selectUserById(@PathVariable(name = "id") int id)
{
User user= userRepository.findById(id).get();
return Response.createOkResp(user);
}
//添加
@PostMapping("/users")
public ResponseResult addUser(User user)
{
userRepository.save(user);
return Response.createOkResp("add success");
}
}
<!-- swagger 核心依赖-->
<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>
swagger2 在springboot框架中使用需要 开启 @EnableSwagger2， 同时它支持自定义ui页面的一些信息
设置上面两个步骤后，打开 http://localhost:8080/swagger-ui.html
就可以看到接口信息
我们把一个Docket类的一个实例添加到Spring的 BeanFactory中，以实现Swagger页面一些展示信息的定制化，例如作者，标题，描述等信息，也可以进行一些响应的配置项，例如扫描的Controller类基础包名等等。
swagger会在初始化时从Spring的 BeanFactory中获取该实例(如果没有则使用默认的Docket实例)，
来完成初始化。
package com.example.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class Swagger2 {
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(
new ApiInfoBuilder()
.contact(new Contact("daimenglaoshi", "", "2398779723@qq.com"))
.title("SpringBoot整合Swagger2")
.build()
);
}
}
上面是对Docket进行一个非常简单的配置。效果如图
package com.example.swagger.controller;
import com.example.swagger.dao.UserRepository;
import com.example.swagger.pojo.User;
import com.example.swagger.util.Response;
import com.example.swagger.util.ResponseResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
@RestController
@Api(tags = "用户管理相关接口")
public class UserController {
@Autowired
private UserRepository userRepository;
//查询所有
@GetMapping("/users")
@ApiOperation("查询所有用户的接口")
public ResponseResult<List<User>> selectUsers()
{
List<User> usersList= userRepository.findAll();
return Response.createOkResp(usersList);
}
//根据id查询
@GetMapping("/users/{id}")
@ApiOperation("根据id查询用户的接口")
@ApiImplicitParam(name = "id", value = "用户id", required = true)
public ResponseResult<User> selectUserById(@PathVariable(name = "id") int id)
{
User user= userRepository.findById(id).get();
return Response.createOkResp(user);
}
//添加
@PostMapping("/users")
@ApiOperation("添加用户")
public ResponseResult addUser(User user)
{
userRepository.save(user);
return Response.createOkResp("add success");
}
}
这里边使用到了多个注解：
@Api注解： 用来标记当前 Controller 的功能。
@ApiOperation注解：用来标记一个方法的作用。
@ApiImplicitParam注解：用来描述一个参数，可以配置参数的中文含义，也可以给参数设置默认值，这样在接口测试的时候可以避免手动输入。
如果有多个参数，则需要使用多个 @ApiImplicitParam 注解来描述，多个 @ApiImplicitParam 注解需要放在一个 @ApiImplicitParams 注解中。
需要注意的是，@ApiImplicitParam 注解中虽然可以指定参数是必填的，但是却不能代替 @RequestParam(required = true) ，前者的必填只是在 Swagger2 框架内必填，抛弃了 Swagger2 ，这个限制就没用了，所以假如开发者需要指定一个参数必填， @RequestParam(required = true) 注解还是不能省略。
如果参数是一个对象（例如上文的添加接口），对于参数的描述也可以放在实体类中。
package com.example.swagger.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import javax.persistence.*;
@Data
@NoArgsConstructor
@AllArgsConstructor
@Entity
@Table(name = "users")
@ApiModel(description = "用户字段")
public class User {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
@ApiModelProperty(value = "用户id", name = "id", example = "1")
private int id;
@ApiModelProperty(value = "用户名", name = "uname", required = true, example = "daimenglaoshi")
private String uname;
@ApiModelProperty(value = "年龄", name = "age", example = "18")
private int age;
}
http://localhost:8080/swagger-ui.html
·
