Spring Boot 入门之路（16）--- Spring Boot 与 Swagger2 的集成

2023-10-26 15:17:10

1 Swagger2 简介

相信大家都有过手写 API 文档的经历吧，公司一般都会有这方面的需求，但是手写 API 文档有一个很严重的问题，效率过于低下了！为解决这个问题， Swagger2 横空出世。Swagger2 可以方便测试后台 restful 形式的接口，实现动态的更新。当我们在后台的接口进行了修改，Swagger2 可以实现自动的更新。

2 添加依赖

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

3 Swagger2 配置类

@Configuration
@EnableSwagger2
public class Swagger2Configuration {

	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.basePackage("edu.szu.test.controller"))
				.paths(PathSelectors.any())
				.build();
	}
	
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("使用swagger2构建的api文档")
				.description("点我关注 https://blog.csdn.net/Geffin")
				.termsOfServiceUrl("https://blog.csdn.net/Geffin")
				.version("1.0")
				.build();
	}
}

4 启动类的配置

@SpringBootApplication
@MapperScan("edu.szu.test.mapper")
@EnableSwagger2
public class TestApplication {

	public static void main(String[] args) {
		SpringApplication.run(TestApplication.class, args);
	}

}

注意要在启动类添加 @EnableSwagger2 注解

5 创建 Controller 文件

@RestController
@Api(tags="测试接口模块")//@Api：用在请求的类上，表示对类的说明
@RequestMapping("/test")
public class BookController {
	
	@Autowired
	BookService bookService;
 
	// 创建线程安全的Map
	static Map<Integer, Book> map = Collections.synchronizedMap(new HashMap<Integer, Book>());
 
	//根据id查询书籍信息
	//@ApiOperation：用在请求的方法上，说明方法的用途、作用,value表示方法的用途,notes为方法的备注
	@ApiOperation(value="根据id查询书籍信息", notes="根据id查询书籍信息")
	//@ApiImplicitParam：用在请求的方法上，表示参数说明,name表示参数名，value为参数的说明，required表示参数是否必须传，paramType表示参数放在哪个地方，dataType表示参数类型
	@ApiImplicitParam(name = "id", value = "书籍ID", required = true, dataType = "int",paramType = "path")
	@RequestMapping(value = "/selectById/{id}",method = RequestMethod.GET)
	public ResponseEntity<JsonResult> selectById (@PathVariable Integer id){
		JsonResult r = new JsonResult();
		try { 
			Book book = bookService.selectById(id);
			r.setResult(book);
			r.setStatus("ok");
		} catch (Exception e) {
			r.setResult(e.getClass().getName() + ":" + e.getMessage());
			r.setStatus("error");
			e.printStackTrace();
		}
		return ResponseEntity.ok(r);
	}
 
	//添加书籍
	@ApiOperation(value="添加书籍", notes="添加书籍")
	@ApiImplicitParam(name = "book", value = "书籍", required = true, dataType = "Book")
	@RequestMapping(value = "/insert",method = RequestMethod.POST)
	public ResponseEntity<JsonResult> insert (@RequestBody Book book){
		JsonResult r = new JsonResult();
		try {
			bookService.insert(book);
			r.setResult(book.getId());
			r.setStatus("ok");
		} catch (Exception e) {
			r.setResult(e.getClass().getName() + ":" + e.getMessage());
			r.setStatus("error");
 
			e.printStackTrace();
		}
		return ResponseEntity.ok(r);
	}
 
	//根据id删除书籍
	@ApiOperation(value="删除书籍", notes="删除书籍")
	@ApiImplicitParam(name = "id", value = "书籍id", required = true, dataType = "int", paramType = "path")
	@RequestMapping(value = "/deleteById/{id}",method = RequestMethod.DELETE)
	public ResponseEntity<JsonResult> deleteById (@PathVariable Integer id){
		JsonResult r = new JsonResult();
		try {
			bookService.deleteById(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);
	}
 
	//修改书籍信息
	@ApiOperation(value="修改书籍信息", notes="修改书籍信息")
	@ApiImplicitParam(name = "book", value = "书籍", required = true, dataType = "Book")
	@RequestMapping(value = "/update",method = RequestMethod.PUT)
	public ResponseEntity<JsonResult> update (@RequestBody Book book){
		JsonResult r = new JsonResult();
		try {
			bookService.update(book);
			r.setResult(book);
			r.setStatus("ok");
		} catch (Exception e) {
			r.setResult(e.getClass().getName() + ":" + e.getMessage());
			r.setStatus("error");
 
			e.printStackTrace();
		}
		return ResponseEntity.ok(r);
	}

}

部分注解说明：

@Api：用在请求的类上，表示对类的说明
@ApiOperation：用在请求的方法上，说明方法的用途、作用,value表示方法的用途,notes为方法的备注
@ApiImplicitParam：用在请求的方法上，表示参数说明,name表示参数名，value为参数的说明，required表示参数是否必须传，paramType表示参数放在哪个地方，dataType表示参数类型

我使用的 Json 格式输出类 JsonResult ：

public class JsonResult {
 
	private String status = null;
 
	private Object result = null;

	public String getStatus() {
		return status;
	}

	public void setStatus(String status) {
		this.status = status;
	}

	public Object getResult() {
		return result;
	}

	public void setResult(Object result) {
		this.result = result;
	}
	
	
 
}