如何讓接口文檔自動生成，SpringBoot中Swagger的使用

目錄

• 一、在SpringBoot項目中配置Swagger2
  • 1、pom.xml中對Swagger2的依賴
  • 2、編寫配置類啟用Swagger
  • 3、配置實體類的文檔
  • 4、配置接口的文檔
  • 5、訪問文檔
• 二、接口前后台分離的配置
  • 1、接口分離
  • 2、對前后台接口進行分組配置

在開發過程中，java后端需要與客戶端進行交互，需要將后端的接口及參數寫成文檔給調用者查閱。一個問題也有此而生，需求改動頻繁，接口設計也會隨之改動，文檔修改的不及時會帶來很大的問題。

Swagger是一個自動生成文檔的工具，可以在線查閱文檔，減少了開發人員的負擔，下面我們就來看看如何在SpringBoot中使用Swagger。

一、在SpringBoot項目中配置Swagger2

1、pom.xml中對Swagger2的依賴

<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、編寫配置類啟用Swagger

Swagger2Config.java

@Configuration //配置類
@EnableSwagger2 //啟用Swagger2
public class Swagger2Config {
    @Bean
    public Docket apiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)//創建Swagger2類型的文檔
                .apiInfo(apiInfo());//apiInfo方法返回配置的接口信息
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("用戶中心微服務前台網站API")//接口標題
                .description("此文檔描述了用戶中心前台網站的基本API接口")//接口描述
                .version("1.0")//接口版本
                .contact(new Contact("Jack", "http://www.jikedaquan.com", "[e-mail]"))//聯系方式：名字、網址、郵箱
                .build();
    }
}

3、配置實體類的文檔

實體類Member

//對實體名生成文檔描述
@ApiModel(value="Member對象")
public class Member{

    //對屬性生成文檔描述
    @ApiModelProperty(value = "學員ID")
    private Long memberId;

    //required 將屬性描述標記為必須
    @ApiModelProperty(value = "手機號",required = true)
    private String mobile;

    @ApiModelProperty(value = "郵箱",required = true)
    private String email;

    @ApiModelProperty(value = "密碼",required = true)
    private String password;

    @ApiModelProperty(value = "用戶名")
    private String userName;

    //將不希望在文檔中看到的屬性使用hidden隱藏
    @ApiModelProperty(value = "邏輯刪除 1已刪除 0未刪除",hidden = true)
    private Boolean deleted;

    //省略其他字段
}

4、配置接口的文檔

控制器接口類

@RestController
//生成api接口的文檔描述
@Api(description = "學員管理")
@RequestMapping("/ucenter/member")
public class MemberController {
    @Autowired
    private MemberService memberService;

    //定義請求方法的名字和詳細描述
    @ApiOperation(value = "注冊學員", notes = "updateTime,createTime無需添加，這是前台系統用戶的注冊功能，前提是用戶已經接收了驗證碼")
    @PostMapping
    public boolean register(
            //定義請求參數的文檔描述 name的值是要描述的參數的名字
            @ApiParam(name = "member", value = "學員對象", required = true)
            @RequestBody Member member) {
        boolean result = memberService.save(member);
        return result;
    }
    
    //省略其他
}

5、訪問文檔

文檔地址：localhost:8080/swagger-ui.html

二、接口前后台分離的配置

為什么要對接口進行前后台分離？因為前台和后台的功能有些相同，但有些差異，例如后台管理員可以刪除用戶，但前台是沒有刪除用戶的功能的，將接口和文檔分離更有利於管理維護。

1、接口分離

前台接口

@RestController
@Api(description = "前端學員管理")
@RequestMapping("/api/ucenter/member")
public class MemberController {
    @Autowired
    private MemberService memberService;

    @ApiOperation(value = "注冊學員", notes = "updateTime,createTime無需添加，這是前台系統用戶的注冊功能，前提是用戶已經接收了驗證碼")
    @PostMapping
    public boolean register(
            @ApiParam(name = "member", value = "學員對象", required = true)
            @RequestBody Member member) {
        boolean result = memberService.save(member);
        return result;
    }
}

后台接口放在同級下的admin包中

@RestController
@Api(description = "學員管理")
@RequestMapping("/admin/ucenter/member")
public class AdminMemberController {
    @Autowired
    private MemberService memberService;

    @ApiOperation(value = "返回所有學員列表")
    @GetMapping
    public List<Member> list() {
        return memberService.list(null);
    }

    @ApiOperation(value = "根據id刪除學員")
    @DeleteMapping(value = "{memberId}")
    public boolean deleteById(@ApiParam(name = "memberId", value = "學員id", required = true)
                              @PathVariable Long memberId) {
        boolean result = memberService.removeById(memberId);
        return result;
    }

    @ApiOperation(value = "注冊學員", notes = "updateTime,createTime無需添加，這是前台系統用戶的注冊功能，前提是用戶已經接收了驗證碼")
    @PostMapping
    public boolean register(
            @ApiParam(name = "member", value = "學員對象", required = true)
            @RequestBody Member member) {
        boolean result = memberService.save(member);
        return result;
    }
}

這樣就有了同一個實體的不同的接口

2、對前后台接口進行分組配置

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    //前台api接口文檔
    public Docket webApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")//組名
                .apiInfo(webApiInfo())
                .select()//創建ApiSelectorBuilder對象
                .paths(Predicates.not(PathSelectors.regex("/admin/.*")))//過濾掉 admin 接口
                .paths(Predicates.not(PathSelectors.regex("/error.*")))//過濾掉 error 接口
                .build();
    }

    @Bean
    //后台管理員api文檔
    public Docket adminApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()//創建ApiSelectorBuilder對象
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))//只顯示 admin 接口
                .build();
    }

    private ApiInfo webApiInfo() {
        return new ApiInfoBuilder()
                .title("用戶中心微服務前台網站API")
                .description("此文檔描述了用戶中心前台網站的基本API接口")
                .version("1.0")
                .contact(new Contact("Jack", "http://www.jikedaquan.com", "[e-mail]"))
                .build();
    }

    private ApiInfo adminApiInfo() {
        return new ApiInfoBuilder()
                .title("用戶中心微服務后台管理系統的API")
                .description("此文檔描述了用戶中心后台管理系統的基本API接口")
                .version("1.0")
                .contact(new Contact("Jack", "http://www.jikedaquan.com", "[e-mail]"))
                .build();
    }
}