Swagger是一個(gè)功能強(qiáng)大的在線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
寫一個(gè)配置類湿镀，加上相關(guān)的注解，代碼如下
@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構(gòu)建api文檔")
.description("歡迎關(guān)注公眾號【禿頭哥編程】")
.version("1.0")
.build();
}
}
其中@Configuration注解表示這是一個(gè)配置類伐憾，@EnableSwagger2開啟Swagger2的功能勉痴。在配置類中需要注入一個(gè)Docket的Bean，該Bean包含了apiInfo树肃，即基本的API文件的描述信息蒸矛，以及包掃描的基本包名等信息。
3胸嘴、生成文檔的注解
Swagger2通過注解來生成API接口文檔雏掠，文檔信息包括接口名、請求方法劣像、參數(shù)乡话、返回信息等。通常情況下用于生成在線API文檔耳奕，下面是常見的注解：
- @Api：修飾整個(gè)類绑青，用于描述Controller。
- @ApiOperation：描述類的方法吮铭，或者說一個(gè)接口时迫。
- @ApiParam：單個(gè)參數(shù)描述颅停。
- @ApiModel：用對象來接收參數(shù)谓晌。
- @ApiProperty：用對象接收參數(shù)時(shí)，描述一個(gè)對象的字段癞揉。
- @ApiResponse：HTTP響應(yīng)的一個(gè)描述纸肉。
- @ApiResponses：HTTP響應(yīng)的整體描述。
- @ApiIgnore：Swagger2忽略該api喊熟。
- @ApiError：發(fā)生錯(cuò)誤返回的信息柏肪。
- @ApiParamImplicit：一個(gè)請求參數(shù)。
- @ApiParamsImplicit：多個(gè)請求參數(shù)芥牌。
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層代碼
構(gòu)建一組RESTful風(fēng)格的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方法，構(gòu)建一組RESTful風(fēng)格的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 = "根據(jù)垃圾的id刪除垃圾搜索記錄")
@DeleteMapping(value = "/{id}")
public Integer deleteGarbage(@PathVariable Integer id) {
return garbageSearchService.deleteGarbage(id);
}
@ApiOperation(value = "更新信息", notes = "根據(jù)指定的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為該接口的詳細(xì)文檔說明算灸。這樣就可以讓Swagger2生成在線的API接口文檔了扼劈，如果不需要某接口生成文檔，只需要加上@ApiIgnore注解即可乎婿。
啟動(dòng)項(xiàng)目测僵，輸入http://localhost:{項(xiàng)目端口號}/swagger-ui.html，瀏覽器就會(huì)生成接口文檔谢翎。
微信圖片_20191001214033.png
點(diǎn)開接口捍靠，還可以看到詳細(xì)信息包括參數(shù)和返回值、錯(cuò)誤碼等信息森逮。
微信圖片_20191001214113.png
