Spring Boot 2.x（十二）：Swagger2的正確玩法

時間 2019-11-17

標籤 spring boot 2.x 十二 swagger2 swagger 正確玩法欄目 Spring 简体版

原文原文鏈接

Swagger2簡介

簡單的來講，Swagger2的誕生就是爲了解決先後端開發人員進行交流的時候API文檔難以維護的痛點，它能夠和咱們的Java程序完美的結合在一塊兒，而且能夠與咱們的另外一開發利器Spring Boot來配合使用。java

開始使用

第一步：導入POM文件

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency> 
        
		<!-- 這裏使用 swagger-bootstrap-ui 替代了原有醜陋的ui，拯救處女座~ -->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.0</version>
        </dependency>
複製代碼

第二步：添加配置類

咱們須要新增一個Swagger2Config 的配置類：git

/** * Swagger2 配置類 * @author vi * @since 2019/3/6 8:31 PM */
@Configuration
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("indi.viyoung.viboot.*"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("viboot-swagger2")	//標題
                .description("Restful-API-Doc")	//描述
                .termsOfServiceUrl("https://www.cnblogs.com/viyoung") //這裏配置的是服務網站，我寫的是個人博客園站點~歡迎關注~
                .contact(new Contact("Vi的技術博客", "https://www.cnblogs.com/viyoung", "18530069930@163.com")) // 三個參數依次是姓名，我的網站，郵箱
                .version("1.0") //版本
                .build();
    }
}
複製代碼

第三步：在啓動類中添加配置

注意必定要記得添加@EnableSwagger2註解github

/** * @author vi * @since 2019/3/6 6:35 PM */
@SpringBootApplication
@ComponentScan(value = "indi.viyoung.viboot.*")
@MapperScan(value = "indi.viyoung.viboot.swagger2.mapper")
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class ViBootSwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ViBootSwaggerApplication.class, args);
    }
}
複製代碼

第四步：經過註解來完成API文檔

1. @Api

註解名稱	註解屬性	做用域	屬性做用
`@Api`	tags	類	說明該類的做用
	value	類	說明該類的做用

舉個🌰：spring

@Api(value = "用戶類控制器",tags="用戶類控制器")
public class UserController {
...
}
複製代碼

2 . @ApiOperation

註解名稱	註解屬性	做用域	屬性做用
`@ApiOperation()`	value	方法	描述方法做用
	notes	方法	提示內容
	tags	方法	分組

舉個🌰：bootstrap

@ApiOperation(value = "獲取用戶列表",notes = "獲取用戶列表")
    public List<User> get() {
     	...   
	}
複製代碼

3. @ApiParam

註解名稱	註解屬性	做用域	屬性做用
`@ApiParam()`	name	方法參數	參數名
	value	方法參數	參數說明
	required	方法參數	是否必填

舉個🌰：後端

@ApiOperation(value="獲取用戶詳細信息", notes="根據url的id來獲取用戶詳細信息")
    public User get(@ApiParam(name="id",value="用戶id",required=true) Long id) {
        log.info("GET..{}...方法執行。。。",id);
        return userService.getById(id);
    }
複製代碼

4. @ApiModel && @ApiModelProperty

註解名稱	註解屬性	做用域	屬性做用
`@ApiModel()`	value	類	對象名
	description	類	描述
`@ApiModelProperty()`	value	方法	字段說明
	name	方法	屬性名
	dataType	方法	屬性類型
	required	方法	是否必填
	example	方法	舉例
	hidden	方法	隱藏

舉個🌰：api

@ApiModel(value="user對象",description="用戶對象user")
public class User implements Serializable {

    private static final long serialVersionUID = 1L;

    @TableId(value = "id", type = IdType.AUTO)
    @ApiModelProperty(value = "用戶ID",example = "1000001",hidden=true)
    private Long id;

    @ApiModelProperty(value="用戶名",required = true,dataType = "String")
    private String userName;
    
    @ApiModelProperty(value = "密碼")
    private String password;
}
複製代碼

5. @ApiImplicitParam && @ApiImplicitParams

`@ApiImplicitParam`能夠單個用於方法至上，多個參數的話能夠把`@ApiImplicitParam`放到`@ApiImplicitParams`中，這裏只羅列`@ApiImplicitParam`的屬性：
複製代碼

註解名稱	註解屬性	做用域	屬性做用
`@ApiImplicitParam()`	value	方法	參數說明
	name	方法	參數名
	dataType	方法	數據類型
	paramType	方法	參數類型
	example	方法	舉例

舉個🌰：緩存

@ApiImplicitParams({
            @ApiImplicitParam(name = "user", value = "用戶實體user", required = true, dataType = "User")
    })
    public void put(User user) {
        userService.updateById(user);
        log.info("PUT方法執行。。。");
    }
複製代碼