您好,登錄后才能下訂單哦!
這期內(nèi)容當(dāng)中小編將會(huì)給大家?guī)碛嘘P(guān)Swagger2 的正確玩法是什么,文章內(nèi)容豐富且以專業(yè)的角度為大家分析和敘述,閱讀完這篇文章希望大家可以有所收獲。
簡(jiǎn)單的來說,Swagger2的誕生就是為了解決前后端開發(fā)人員進(jìn)行交流的時(shí)候API文檔難以維護(hù)的痛點(diǎn),它可以和我們的Java程序完美的結(jié)合在一起,并且可以與我們的另一開發(fā)利器Spring Boot來配合使用。
<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>
#### 第二步:添加配置類
我們需要新增一個(gè)Swagger2Config 的配置類:
/** * 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") //標(biāo)題 .description("Restful-API-Doc") //描述 .termsOfServiceUrl("https://www.cnblogs.com/viyoung") //這里配置的是服務(wù)網(wǎng)站,我寫的是我的博客園站點(diǎn)~歡迎關(guān)注~ .contact(new Contact("Vi的技術(shù)博客", "https://www.cnblogs.com/viyoung", "18530069930@163.com")) // 三個(gè)參數(shù)依次是姓名,個(gè)人網(wǎng)站,郵箱 .version("1.0") //版本 .build(); } }
注意一定要記得添加@EnableSwagger2
注解
/** * @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); } }
1. @Api
注解名稱 | 注解屬性 | 作用域 | 屬性作用 |
---|---|---|---|
@Api | tags | 類 | 說明該類的作用 |
value | 類 | 說明該類的作用 |
舉個(gè)????:
@Api(value = "用戶類控制器",tags="用戶類控制器") public class UserController { ... }
2 . @ApiOperation
注解名稱 | 注解屬性 | 作用域 | 屬性作用 |
---|---|---|---|
@ApiOperation() | value | 方法 | 描述方法作用 |
notes | 方法 | 提示內(nèi)容 | |
tags | 方法 | 分組 |
舉個(gè)????:
@ApiOperation(value = "獲取用戶列表",notes = "獲取用戶列表") public List<User> get() { ... }
3. @ApiParam
注解名稱 | 注解屬性 | 作用域 | 屬性作用 |
---|---|---|---|
@ApiParam() | name | 方法參數(shù) | 參數(shù)名 |
value | 方法參數(shù) | 參數(shù)說明 | |
required | 方法參數(shù) | 是否必填 |
舉個(gè)????:
@ApiOperation(value="獲取用戶詳細(xì)信息", notes="根據(jù)url的id來獲取用戶詳細(xì)信息") public User get(@ApiParam(name="id",value="用戶id",required=true) Long id) { log.info("GET..{}...方法執(zhí)行。。。",id); return userService.getById(id); }
4. @ApiModel && @ApiModelProperty
注解名稱 | 注解屬性 | 作用域 | 屬性作用 |
---|---|---|---|
@ApiModel() | value | 類 | 對(duì)象名 |
description | 類 | 描述 | |
@ApiModelProperty() | value | 方法 | 字段說明 |
name | 方法 | 屬性名 | |
dataType | 方法 | 屬性類型 | |
required | 方法 | 是否必填 | |
example | 方法 | 舉例 | |
hidden | 方法 | 隱藏 |
舉個(gè)????:
@ApiModel(value="user對(duì)象",description="用戶對(duì)象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`可以單個(gè)用于方法至上,多個(gè)參數(shù)的話可以把`@ApiImplicitParam`放到`@ApiImplicitParams`中,這里只羅列`@ApiImplicitParam`的屬性:
注解名稱 | 注解屬性 | 作用域 | 屬性作用 |
---|---|---|---|
@ApiImplicitParam() | value | 方法 | 參數(shù)說明 |
name | 方法 | 參數(shù)名 | |
dataType | 方法 | 數(shù)據(jù)類型 | |
paramType | 方法 | 參數(shù)類型 | |
example | 方法 | 舉例 |
舉個(gè)????:
@ApiImplicitParams({ @ApiImplicitParam(name = "user", value = "用戶實(shí)體user", required = true, dataType = "User") }) public void put(User user) { userService.updateById(user); log.info("PUT方法執(zhí)行。。。"); }
這里需要注意一點(diǎn),我們并沒有在注解中寫圖中圈中的兩個(gè)參數(shù),這個(gè)是去讀取了我們剛剛為User
類的注解,并將用戶名設(shè)置為必填!
6.@ApiResposne && @ApiResponses
@ApiResponses
與@ApiResponse
的關(guān)系和@ApiImplicitParam
&& @ApiImplicitParams
的關(guān)系和用法都是類似的
注解名稱 | 注解屬性 | 作用域 | 屬性作用 |
---|---|---|---|
@ApiResponse() | response | 方法 | 返回類 |
code | 方法 | 返回碼 | |
message | 方法 | 返回信息 | |
examples | 方法 | 例子 |
先貼幾張spring-fox的ui(正是我們所熟知的那一套)
相信看到這里,大家心里對(duì)于這兩套UI的選擇應(yīng)該都有個(gè)答案了,當(dāng)然bootstrap風(fēng)格的ui不僅好看,而且有各種強(qiáng)大的功能~
導(dǎo)出md文檔
參數(shù)緩存
上述就是小編為大家分享的Swagger2 的正確玩法是什么了,如果剛好有類似的疑惑,不妨參照上述分析進(jìn)行理解。如果想知道更多相關(guān)知識(shí),歡迎關(guān)注億速云行業(yè)資訊頻道。
免責(zé)聲明:本站發(fā)布的內(nèi)容(圖片、視頻和文字)以原創(chuàng)、轉(zhuǎn)載和分享為主,文章觀點(diǎn)不代表本網(wǎng)站立場(chǎng),如果涉及侵權(quán)請(qǐng)聯(lián)系站長(zhǎng)郵箱:is@yisu.com進(jìn)行舉報(bào),并提供相關(guān)證據(jù),一經(jīng)查實(shí),將立刻刪除涉嫌侵權(quán)內(nèi)容。