SpringBoot（七）：SpringBoot整合Swagger2

小灰灰 2022-06-12 00:26 283阅读 0赞

> 相信各位在公司写API文档数量应该不少，当然如果你还处在自己一个人开发前后台的年代，当我没说，如今为了前后台更好的对接，还是为了以后交接方便，都有要求写API文档。

手写Api文档的几个痛点：

1.  文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
2.  接口返回结果不明确
3.  不能直接在线测试接口，通常需要使用工具，比如postman
4.  接口文档太多，不好管理

Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

其他的不多说，想要了解Swagger的，可以去Swagger官网，可以直接使用Swagger editor编写接口文档，当然我们这里讲解的是SpringBoot整合Swagger2，直接生成接口文档的方式。

### 一、依赖 ###

<dependency>
    	<groupId>io.springfox</groupId>
    	<artifactId>springfox-swagger2</artifactId>
    	<version>2.6.1</version>
    </dependency>
    
    <dependency>
    	<groupId>io.springfox</groupId>
    	<artifactId>springfox-swagger-ui</artifactId>
    	<version>2.6.1</version>
    </dependency>

### 二、Swagger配置类 ###

其实这个配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径，不然生成的文档扫描不到接口。

package cn.saytime;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    
    /** * @author zh * @ClassName cn.saytime.Swgger2 * @Description * @date 2017-07-10 22:12:31 */
    @Configuration
    public class Swagger2 {
    
    	@Bean
    	public Docket createRestApi() {
    		return new Docket(DocumentationType.SWAGGER_2)
    				.apiInfo(apiInfo())
    				.select()
    				.apis(RequestHandlerSelectors.basePackage("cn.saytime.web"))
    				.paths(PathSelectors.any())
    				.build();
    	}
    	
    	private ApiInfo apiInfo() {
    		return new ApiInfoBuilder()
    				.title("springboot利用swagger构建api文档")
    				.description("简单优雅的restfun风格，http://blog.csdn.net/saytime")
    				.termsOfServiceUrl("http://blog.csdn.net/saytime")
    				.version("1.0")
    				.build();
    	}
    }

> 用@Configuration注解该类，等价于XML中配置beans；用@Bean标注方法等价于XML中配置bean。

Application.class 加上注解@EnableSwagger2 表示开启Swagger

package cn.saytime;
    
    import org.springframework.boot.SpringApplication;
    import org.springframework.boot.autoconfigure.SpringBootApplication;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @SpringBootApplication
    @EnableSwagger2
    public class SpringbootSwagger2Application { 
    
    	public static void main(String[] args) {
    		SpringApplication.run(SpringbootSwagger2Application.class, args);
    	}
    }

### 三、Restful 接口 ###

package cn.saytime.web;
    
    import cn.saytime.bean.JsonResult;
    import cn.saytime.bean.User;
    import io.swagger.annotations.Api;
    import io.swagger.annotations.ApiImplicitParam;
    import io.swagger.annotations.ApiImplicitParams;
    import io.swagger.annotations.ApiOperation;
    import org.springframework.http.ResponseEntity;
    import org.springframework.web.bind.annotation.PathVariable;
    import org.springframework.web.bind.annotation.RequestBody;
    import org.springframework.web.bind.annotation.RequestMapping;
    import org.springframework.web.bind.annotation.RequestMethod;
    import org.springframework.web.bind.annotation.RestController;
    import springfox.documentation.annotations.ApiIgnore;
    
    import java.util.ArrayList;
    import java.util.Collections;
    import java.util.HashMap;
    import java.util.List;
    import java.util.Map;
    
    /** * @author zh * @ClassName cn.saytime.web.UserController * @Description */
    @RestController
    public class UserController {
    
    	// 创建线程安全的Map
    	static Map<Integer, User> users = Collections.synchronizedMap(new HashMap<Integer, User>());
    
    	/** * 根据ID查询用户 * @param id * @return */
    	@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    	@RequestMapping(value = "user/{id}", method = RequestMethod.GET)
    	public ResponseEntity<JsonResult> getUserById (@PathVariable(value = "id") Integer id){
    		JsonResult r = new JsonResult();
    		try {
    			User user = users.get(id);
    			r.setResult(user);
    			r.setStatus("ok");
    		} catch (Exception e) {
    			r.setResult(e.getClass().getName() + ":" + e.getMessage());
    			r.setStatus("error");
    			e.printStackTrace();
    		}
    		return ResponseEntity.ok(r);
    	}
    
    	/** * 查询用户列表 * @return */
    	@ApiOperation(value="获取用户列表", notes="获取用户列表")
    	@RequestMapping(value = "users", method = RequestMethod.GET)
    	public ResponseEntity<JsonResult> getUserList (){
    		JsonResult r = new JsonResult();
    		try {
    			List<User> userList = new ArrayList<User>(users.values());
    			r.setResult(userList);
    			r.setStatus("ok");
    		} catch (Exception e) {
    			r.setResult(e.getClass().getName() + ":" + e.getMessage());
    			r.setStatus("error");
    			e.printStackTrace();
    		}
    		return ResponseEntity.ok(r);
    	}
    
    	/** * 添加用户 * @param user * @return */
    	@ApiOperation(value="创建用户", notes="根据User对象创建用户")
    	@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
    	@RequestMapping(value = "user", method = RequestMethod.POST)
    	public ResponseEntity<JsonResult> add (@RequestBody User user){
    		JsonResult r = new JsonResult();
    		try {
    			users.put(user.getId(), user);
    			r.setResult(user.getId());
    			r.setStatus("ok");
    		} catch (Exception e) {
    			r.setResult(e.getClass().getName() + ":" + e.getMessage());
    			r.setStatus("error");
    
    			e.printStackTrace();
    		}
    		return ResponseEntity.ok(r);
    	}
    
    	/** * 根据id删除用户 * @param id * @return */
    	@ApiOperation(value="删除用户", notes="根据url的id来指定删除用户")
    	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    	@RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
    	public ResponseEntity<JsonResult> delete (@PathVariable(value = "id") Integer id){
    		JsonResult r = new JsonResult();
    		try {
    			users.remove(id);
    			r.setResult(id);
    			r.setStatus("ok");
    		} catch (Exception e) {
    			r.setResult(e.getClass().getName() + ":" + e.getMessage());
    			r.setStatus("error");
    
    			e.printStackTrace();
    		}
    		return ResponseEntity.ok(r);
    	}
    
    	/** * 根据id修改用户信息 * @param user * @return */
    	@ApiOperation(value="更新信息", notes="根据url的id来指定更新用户信息")
    	@ApiImplicitParams({
    			@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long",paramType = "path"),
    			@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
    	})
    	@RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
    	public ResponseEntity<JsonResult> update (@PathVariable("id") Integer id, @RequestBody User user){
    		JsonResult r = new JsonResult();
    		try {
    			User u = users.get(id);
    			u.setUsername(user.getUsername());
    			u.setAge(user.getAge());
    			users.put(id, u);
    			r.setResult(u);
    			r.setStatus("ok");
    		} catch (Exception e) {
    			r.setResult(e.getClass().getName() + ":" + e.getMessage());
    			r.setStatus("error");
    
    			e.printStackTrace();
    		}
    		return ResponseEntity.ok(r);
    	}
    
    	@ApiIgnore//使用该注解忽略这个API
    	@RequestMapping(value = "/hi", method = RequestMethod.GET)
    	public String jsonTest() {
    		return " hi you!";
    	}
    }

Json格式输出类 JsonResult.class

package cn.saytime.bean;
    
    public class JsonResult {
    
    	private String status = null;
    
    	private Object result = null;
    
    	// Getter Setter
    }

实体User.class

package cn.saytime.bean;
    
    import java.util.Date;
    
    /** * @author zh * @ClassName cn.saytime.bean.User * @Description */
    public class User { 
    
    	private int id;
    	private String username;
    	private int age;
    	private Date ctm;
    
    	// Getter Setter
    }

项目结构：

![这里写图片描述][SouthEast]

### 四、Swagger2文档 ###

启动SpringBoot项目，访问 [http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html]

![这里写图片描述][SouthEast 1]

具体里面的内容以及接口测试，应该一看就懂了。这里就不一一截图了。

### 五、Swagger注解 ###

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

*  @Api：修饰整个类，描述Controller的作用
 *  @ApiOperation：描述一个类的一个方法，或者说一个接口
 *  @ApiParam：单个参数描述
 *  @ApiModel：用对象来接收参数
 *  @ApiProperty：用对象接收参数时，描述对象的一个字段
 *  @ApiResponse：HTTP响应其中1个描述
 *  @ApiResponses：HTTP响应整体描述
 *  @ApiIgnore：使用该注解忽略这个API
 *  @ApiError ：发生错误返回的信息
 *  @ApiImplicitParam：一个请求参数
 *  @ApiImplicitParams：多个请求参数

[SouthEast]: /images/20220612/a4baa857cd2148f8bc10edaf52acc350.png
[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[SouthEast 1]: /images/20220612/38d96dc9106943f9bb35d63c069cc589.png