springboot集成swagger2生產API文檔

springboot項目中，前後端分離開發，前端頁面要調用後端api處理業務就需要知道api接口的詳細說明，包括調用路徑、調用方式、入參、出參等相關要素。在早些年的時候，前後端人員都是通過編寫word接口文檔方式進行溝通，工作量非常大，溝通效率也不高。在swigger出現後，開發人員徹底從編寫word接口文檔中解放出來，把精力放在具體的業務實現上。
swigger是一款能夠自動生成api接口文檔的框架，我們只需要根據swigger提供的語言規範在API接口處添加對應的描述，它就能自動生成接口文檔，並能夠在線查看，大大縮減了前後端開發人員的溝通成本。

1.添加swagger依賴

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

2.配置swagger

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("xxx林業平臺")
                .description("xxx林業平臺後臺api接口文檔")
                .termsOfServiceUrl("127.0.0.1:9000") //根據本機端口配置
                .version("1.0")
                .build();
    }

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cc.app")) //api包路徑
                .paths(PathSelectors.regex("/api/.*")) //api的path
                .build();
    }
}

3.使用swagger註解
通過swagger提供的註解對api接口進行描述，swagger根據描述生成api接口文檔。
常用的註解如下：
@Api(value = “/api/jc_sp_line”, description = “樣線監測數據”) 用於類描述
@ApiOperation(value = “根據ID查詢信息”,notes = “根據ID查詢信息”) 用於方法描述
@ApiImplicitParam(name = “params”, value = “UID 如：{id:‘aa’}” ) 用於參數字段描述
@ApiImplicitParams({
@ApiImplicitParam(name = “name”, value = “姓名”),
@ApiImplicitParam(name = “age”, value = “年齡”)
}) 用於多個參數字段描述

具體代碼使用如下：

/**
 * 樣線監測數據模塊控制層
 * creater shah on 2020/02/05
 **/
@Api(value = "/api/jc_sp_line", description = "樣線監測數據")
@RestController
@RequestMapping("/api/jc_sp_line")
public class JcSPLineController extends BaseController{
    private static Logger logger = LoggerFactory.getLogger(JcSPLineController.class);

    @Autowired
    public JcSPLineService service;


    /**
     * 根據ID查詢信息
     * @param uid
     * @return
     */
    @ApiOperation(value = "根據ID查詢信息",notes = "根據ID查詢信息")
    @RequestMapping(value = "/findAllByID", method = RequestMethod.GET)
    public Object findAllByID(String uid){
        JcSPLine bean=service.findInfoByID(uid);
        return RtnData.ok(bean);
    }

    @ApiOperation(value = "單筆刪除樣線監測數據",notes = "單筆刪除樣線監測數據")
    @ApiImplicitParam(name = "params", value = "UID 如：{id:'aa'}" )
    @RequestMapping(value = "/delete",method = RequestMethod.POST)
    public RtnData delete(@RequestBody Map params){
        service.delete((String) params.get("id"));
        return RtnData.ok("success");
    }

4.查看swagger生成的接口文檔
項目啓動後，訪問地址：http://localhost:9000/swagger-ui.html，可以看到API文檔界面：

點開一個controller條目，可以看到API接口列表：

點開一個接口方法，可以看到接口參數詳情：

是不是很詳細，是不是很方便！！！

*媽媽以後再也不用擔心我跟前端妹子吵架了，好開心！