Spring Boot Road Primer (16) --- Spring Boot integration with Swagger2

Disclaimer: This article is a blogger original article, follow the CC 4.0 BY-SA copyright agreement, reproduced, please attach the original source link and this statement.

This link: https://blog.csdn.net/Geffin/article/details/100184299

1 Swagger2 Introduction

I believe we have had the experience of it handwritten API documentation, companies generally have needs in this area, but the handwriting API documentation has a very serious problem, too inefficient up! To solve this problem, Swagger2 turned out. Swagger2 can easily test the background restful form of interface, dynamic updates. When we were modified in the background of the interface, Swagger2 can be automatically updated.

2 Add dependence

<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 class

@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 startup class configuration

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

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

}

Note To add @ EnableSwagger2 annotation startup class

5 Create Controller file

@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);
	}

}

Part of the explanatory notes:

1. @Api: used in the requested class, an explanation of the class
2. @ApiOperation: The method used in the request that the use of the method, the effect, value represents the use of the method, the method of the remark Notes
3. @ApiImplicitParam: the method used in the request, expressed parameter description, name represents the parameter name, value as a description of the parameters, required parameters must indicate whether pass, paramType which represents a parameter in place, dataType parameter indicating the type

Json format output class I use 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;
	}
	
	
 
}

6 project structure

My project is structured as follows

7 View Swagger2 document

Start SpringBoot project, visit http: // localhost: 8080 / swagger-ui.html

8 Use the test function

Observed that it returns a success

Open our database and found that the data has been inserted successfully, on behalf of Spring Boot has been successfully integrated with Swagger2.

Reference: SpringBoot (seven): SpringBoot integration Swagger2