Swagger是一个功能强大的在线API文档框架，目前它的版本是2.x，所以称为Swagger2。Swagger2提供了在线文档的查阅和测试功能。下面看看怎么在SpringBoot中集成Swagger2。
1、引入依赖
在pom文件引入下面的依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
2、配置Swagger2
写一个配置类，加上相关的注解，代码如下
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.codeliu.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("SpringBoot利用swagger构建api文档")
.description("欢迎关注公众号【秃头哥编程】")
.version("1.0")
.build();
}
}
其中@Configuration注解表示这是一个配置类，@EnableSwagger2开启Swagger2的功能。在配置类中需要注入一个Docket的Bean，该Bean包含了apiInfo，即基本的API文件的描述信息，以及包扫描的基本包名等信息。
3、生成文档的注解
Swagger2通过注解来生成API接口文档，文档信息包括接口名、请求方法、参数、返回信息等。通常情况下用于生成在线API文档，下面是常见的注解：
- @Api：修饰整个类，用于描述Controller。
- @ApiOperation：描述类的方法，或者说一个接口。
- @ApiParam：单个参数描述。
- @ApiModel：用对象来接收参数。
- @ApiProperty：用对象接收参数时，描述一个对象的字段。
- @ApiResponse：HTTP响应的一个描述。
- @ApiResponses：HTTP响应的整体描述。
- @ApiIgnore：Swagger2忽略该api。
- @ApiError：发生错误返回的信息。
- @ApiParamImplicit：一个请求参数。
- @ApiParamsImplicit：多个请求参数。
4、编写dao层代码
@Mapper
public interface GarbageSearchMapper {
GarbageSearch findGarbageByName(String name);
List<GarbageSearch> findAll();
Integer addGarbage(GarbageSearch garbageSearch);
Integer updateGarbage(GarbageSearch garbageSearch);
Integer deleteGarbage(Integer id);
}
上面就是一些普通的增删改查。
5、编写Service层代码
构建一组RESTful风格的API接口。
@Service
public class GarbageSearchServiceImpl implements GarbageSearchService {
@Autowired
private GarbageSearchMapper garbageSearchMapper;
public GarbageSearch findGarbageByName(String name) {
return garbageSearchMapper.findGarbageByName(name);
}
public List<GarbageSearch> findAll() {
return garbageSearchMapper.findAll();
}
public Integer addGarbage(GarbageSearch garbageSearch) {
return garbageSearchMapper.addGarbage(garbageSearch);
}
public Integer updateGarbage(GarbageSearch garbageSearch) {
return garbageSearchMapper.updateGarbage(garbageSearch);
}
public Integer deleteGarbage(Integer id) {
return garbageSearchMapper.deleteGarbage(id);
}
}
6、Web层
在该层通过Get、Post、Delete、Put这四种Http方法，构建一组RESTful风格的API。
@RestController
@RequestMapping("/garbage/search")
public class GarbageSearchController {
@Autowired
private GarbageSearchService garbageSearchService;
@ApiOperation(value = "垃圾列表", notes = "获取所有垃圾")
@GetMapping(value = {""})
public List<GarbageSearch> getGarbages() {
List<GarbageSearch> garbages = garbageSearchService.findAll();
return garbages;
}
@ApiOperation(value = "增加垃圾", notes = "增加一条垃圾搜索记录")
@PostMapping(value = "")
public Integer postGarbage(@RequestBody GarbageSearch garbageSearch) {
return garbageSearchService.addGarbage(garbageSearch);
}
@ApiOperation(value = "删除垃圾搜索记录", notes = "根据垃圾的id删除垃圾搜索记录")
@DeleteMapping(value = "/{id}")
public Integer deleteGarbage(@PathVariable Integer id) {
return garbageSearchService.deleteGarbage(id);
}
@ApiOperation(value = "更新信息", notes = "根据指定的id更新垃圾搜索记录")
@PutMapping(value = "/{id}")
public Integer putGarbage(@PathVariable Integer id, @RequestBody GarbageSearch garbageSearch) {
GarbageSearch garbageSearch1 = new GarbageSearch();
garbageSearch1.setGarbageSearchCount(garbageSearch.getGarbageSearchCount() + 1);
garbageSearch1.setGarbageSearchId(id);
return garbageSearchService.updateGarbage(garbageSearch);
}
@ApiIgnore
@GetMapping(value = "/hi")
public String test() {
return "hello world";
}
}
通过@ApiOperation注解描述生成在线文档的具体API的说明，其中value值为该接口的名称，note为该接口的详细文档说明。这样就可以让Swagger2生成在线的API接口文档了，如果不需要某接口生成文档，只需要加上@ApiIgnore注解即可。
启动项目，输入http://localhost:{项目端口号}/swagger-ui.html，浏览器就会生成接口文档。
微信图片_20191001214033.png
点开接口，还可以看到详细信息包括参数和返回值、错误码等信息。
微信图片_20191001214113.png
