SpringBoot項目集成Swagger2，從此不再寫接口文檔

自從使用前後端分離後，維護接口文檔基本上是必不可少的工作。目前的狀況是，後端需要先將接口文檔寫好，然後交由前端同步開發，但是問題是，在開發過程中，必然會出現需要修改接口的情形，此時就需要及時修改接口文檔。即便是接口沒有做修改，前端部分同事由於對後端瞭解較少，還是存在部分接口需要你給他苦口婆心的解釋，費時又費力。Swagger2 可以很好地解決上面出現需要及時更新接口文檔的情況，它可以動態生成Api接口文檔，降低溝通成本，促進項目高效開發。

下面將介紹如何使用spring boot整合swagger2 生成在線的API文檔。

1. pom.xml 添加 swagger 依賴

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

2. application.properties 添加 swagger 啓用開關（上線後關閉）

swagger.enable=true

3. swagger 配置類

@Configuration
@EnableSwagger2
public class SwaggerConfig {
	
	@Value("${swagger.enable}")
	private boolean enableSwagger;
	
	@Bean
	public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
        		.enable(enableSwagger)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.chinamobile.cmss.vote.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(apiInfo());
    }
	
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
		        .title("SpringBoot整合Swagger")
		        .description("SpringBoot整合Swagger")
		        .version("1.0")
		        .contact(new Contact("接口責任人","https://www.baidu.com","[email protected]"))
		        .license("Apache License Version 2.0")
		        .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
		        .description("接口描述")
		        .build();
	}
}

4. 接口添加 Swagger 註解

@Api(tags = "Swagger使用樣例相關接口")
@RestController
@RequestMapping("/swagger")
public class SwaggerExampleController {
	
	@GetMapping("/getExample")
	@ApiOperation("swagger get 方式接口樣例")
	@ApiImplicitParams({
		@ApiImplicitParam(name = "name", value = "名稱", dataType = "String", paramType = "query", required = true)
	})
	@ApiResponses({
		@ApiResponse(code = 200, message = "請求成功"),
		@ApiResponse(code = 401, message = "未授權"),
		@ApiResponse(code = 403, message = "禁止訪問"),
		@ApiResponse(code = 404, message = "資源不存在"),
		@ApiResponse(code = 1000, message = "系統異常")
	})
	public Object getExample(@RequestParam("name")final String name) {
		
		return name;
	}
	
	@PostMapping("/postExample1")
	@ApiOperation("swagger post 方式接口樣例1")
	@ApiImplicitParams({
		@ApiImplicitParam(name = "name", value = "姓名", required = true),
		@ApiImplicitParam(name = "phone", value = "手機號", defaultValue = "無")
	})
	@ApiResponses({
		@ApiResponse(code = 200, message = "請求成功"),
		@ApiResponse(code = 401, message = "未授權"),
		@ApiResponse(code = 403, message = "禁止訪問"),
		@ApiResponse(code = 404, message = "資源不存在"),
		@ApiResponse(code = 1000, message = "系統異常")
	})
	public Object postExample1(final String name, final String phone) {
		
		return name + "【" + phone + "】";
	}
	
	@PostMapping("/postExample2")
	@ApiOperation("swagger post 方式接口樣例2")
	@ApiResponses({
		@ApiResponse(code = 200, message = "請求成功"),
		@ApiResponse(code = 401, message = "未授權"),
		@ApiResponse(code = 403, message = "禁止訪問"),
		@ApiResponse(code = 404, message = "資源不存在"),
		@ApiResponse(code = 1000, message = "系統異常")
	})
	public Object postExample2(@RequestBody final UserDto user) {
		
		return user;
	}
	
	
}

5. 對於使用對象接收 POST 請求參數，需要給對象添加註解

@ApiModel(description = "用戶信息")
public class UserDto implements Serializable {

    private static final long serialVersionUID = 1L;

    /** id **/
    @ApiModelProperty(value = "用戶ID", dataType = "Long")
    private Long id;

    /** 手機號 **/
    @ApiModelProperty(value = "手機號", dataType = "String")
    private String phone;

    /** 名稱 **/
    @ApiModelProperty(hidden = true)
    private String name;

    /** 郵箱 **/
    @ApiModelProperty(value = "郵箱", dataType = "String")
    private String mail;

    /** 登錄次數 **/
    @ApiModelProperty(hidden = true)
    private Integer loginCnt;

    -- 省略getter、setter --
}

6. 截圖