前言

前后端分離開(kāi)發(fā)模式中，api文檔是最好的溝通方式。今天就來(lái)說(shuō)一說(shuō)如何整合Swagger生成一套漂亮、美觀、實(shí)用的接口文檔。
源碼傳送門：
https://gitee.com/huoqstudy/xiliu-admin.git

一、Swagger介紹

Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)，它有著如下的優(yōu)點(diǎn)：
1. 及時(shí)性 (接口變更后，能夠及時(shí)準(zhǔn)確地通知相關(guān)前后端開(kāi)發(fā)人員)
2. 規(guī)范性 (并且保證接口的規(guī)范性，如接口的地址，請(qǐng)求方式，參數(shù)及響應(yīng)格式和錯(cuò)誤信息)
3. 一致性 (接口信息一致，不會(huì)出現(xiàn)因開(kāi)發(fā)人員拿到的文檔版本不一致，而出現(xiàn)分歧)
4. 可測(cè)性 (直接在接口文檔上進(jìn)行測(cè)試，以方便理解業(yè)務(wù))

二、配置Swagger

1. 添加依賴

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

2. 創(chuàng)建Swagger2配置文件

代碼如下（示例）：

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket apiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 調(diào)用apiInfo方法,創(chuàng)建一個(gè)ApiInfo實(shí)例,里面是展示在文檔頁(yè)面信息內(nèi)容
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //大標(biāo)題
                .title("接口文檔")
                //詳細(xì)描述
                .description("接口文檔")
                //版本
                .version("1.0")
                //作者
                .contact(new Contact("xiliu", "http://www.xxx.com", "277769738@qq.com"))
                .build();
    }

}

3. 重啟服務(wù)查看接口

訪問(wèn)路徑：
http://localhost:8081/swagger-ui.html ，出現(xiàn)生成的文檔頁(yè)面。但是作為一個(gè)有審美追求的人，這ui也太難看了吧，果斷放棄，更換成Knife4j

4. 使用Knife4j

Knife4j的前身是swagger-bootstrap-ui，前身swagger-bootstrap-ui是一個(gè)純swagger-ui的ui皮膚項(xiàng)目。但是隨著項(xiàng)目的發(fā)展,面對(duì)越來(lái)越多的個(gè)性化需求，不得不編寫(xiě)后端JAVA代碼以滿足新的需求，因此，項(xiàng)目正式更名為knife4j,取名knife4j是希望它能像一把匕首一樣小巧、輕量，并且功能強(qiáng)悍，更名也是希望把她做成一個(gè)為Swagger接口文檔服務(wù)的通用性解決方案，不僅僅只是專注于前端Ui前端。

4.1 添加依賴

需要?jiǎng)h除原來(lái)引用的swagger依賴

<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>knife4j-spring-boot-starter</artifactId>
	<version>2.0.7</version>
</dependency>

4.2 修改配置類

@Configuration
@EnableSwagger2WebMvc
public class Swagger2Config {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("接口文檔")
                        .description("# 接口文檔")
                        .termsOfServiceUrl("http://www.xx.com/")
                        .contact("277769738@qq.com")
                        .version("1.0")
                        .build())
                //分組名稱
                .groupName("2.X版本")
                .select()
                //這里指定Controller掃描包路徑
                .apis(RequestHandlerSelectors.basePackage("com.java.xiliu"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    /*@Bean
    public Docket apiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 調(diào)用apiInfo方法,創(chuàng)建一個(gè)ApiInfo實(shí)例,里面是展示在文檔頁(yè)面信息內(nèi)容
                .apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //大標(biāo)題
                .title("接口文檔")
                //詳細(xì)描述
                .description("接口文檔")
                //版本
                .version("1.0")
                //作者
                .contact(new Contact("xiliu", "http://www.xxx.com", "277769738@qq.com"))
                .build();

    }*/

}

4.3 重啟服務(wù)查看接口

訪問(wèn)地址：
http://localhost:8081/doc.html，這個(gè)ui界面看起來(lái)就更美觀，更符合國(guó)人的使用習(xí)慣。

5. 定義接口說(shuō)明和參數(shù)說(shuō)明

定義在類上：@Api

定義在方法上：@ApiOperation

定義在參數(shù)上：@ApiParam

@Api(tags = "用戶管理")
@RestController
@RequestMApping("/ucenter/member")
public class MemberController {

    @Autowired
    private MemberService memberService;

    @ApiOperation(value = "所有用戶列表")
    @GetMapping(value = "/getAll")
    public List<Member> list(){
        return memberService.list(null);
    }

    @ApiOperation(value = "根據(jù)id刪除用戶")
    @PostMapping(value = "del/{memberId}")
    public boolean deleteById(
            @ApiParam(name = "memberId", value = "用戶ID", required = true)
            @PathVariable Long memberId){
        return memberService.removeById(memberId);
    }

    @ApiOperation(value = "保存用戶")
    @PostMapping(value = "save")
    public boolean save(
            @ApiParam(name = "member", value = "用戶對(duì)象json", required = true)
            @RequestBody Member member){
        if (null == member.getMemberId()) {
            return memberService.save(member);
        }
        return memberService.updateById(member);
    }

}

總結(jié)

感謝大家的閱讀，以上就是今天要講的內(nèi)容，本文簡(jiǎn)單介紹了如何整合Swagger生成api接口文檔，雖然很多人噴Swagger，不好用，基于注解，代碼入侵很強(qiáng)，等等 很多原因。但總體來(lái)看，swagger發(fā)展至今，包括在各個(gè)語(yǔ)言，NodeJs、.net、java、php等等，它可以說(shuō)是一個(gè)有些接口規(guī)范的東西，從開(kāi)始，到一步步規(guī)范，其實(shí)是一個(gè)很艱難的過(guò)程，任何事物，都不是盡善盡美的，swagger也是一樣，至少它給這么多語(yǔ)言提供了一種文檔生成的解決方案，其價(jià)值就遠(yuǎn)超它本身的缺點(diǎn)。

最后弱弱地問(wèn)一句，你們的項(xiàng)目用swagger了嗎？