隨著網路專案前後端分離方式的流行,前端與後端交給不同的人員開發,專案溝通成本也隨之提高。
主要表現在WebAPI介面的溝通,Swagger2 應運而生,它可以動態產生Api介面文檔,降低溝通成本,促進專案高效開發。
下面討論Swagger2及swagger-bootstrap-ui在SpringBoot上的整合
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency>
可對照進行對應的修改
@Configuration @EnableSwagger2 @EnableSwaggerBootstrapUI @Profile({"dev","test"}) public class Swagger2Config { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("") //指定分组,对应(/v2/api-docs?group=) .pathMapping("") //base地址,最终会拼接Controller中的地址 .apiInfo(apiInfo()) .select() //为当前包路径 // .apis(RequestHandlerSelectors.any()) .apis(RequestHandlerSelectors.basePackage("com.riskeys.sd.custom")) .paths(PathSelectors.any()) .build(); } //构建 api文档的详细信息函数 private ApiInfo apiInfo() { return new ApiInfoBuilder() //页面标题 .title("XXX API对接文档") .description("XX API对接文档") //描述 //创建人 .contact(new Contact("yuhei001", "https://blog.csdn.net/Yuhei0", "18616591658@163.com")) //版本号 .version("1.0") //描述 .description("API 描述") .build(); } }
http://127.0.0.1:10086/swagger-ui.html
在步驟二的基礎上進行如下操作
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.6</version> </dependency>
未配置的情況下,有可能存取封包error.9996。
實作WebMvcConfigurer接口,或是WebMvcConfigurationSupport(老版的SpringBoot),實作addResourceHandlers方法,加上如下所示程式碼即可。
@Configuration public class AppWebConfig extends WebMvcConfigurationSupport{ @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); // 解决 doc.html 404 报错 registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); } }
或
@Configuration public class AppWebConfig extends WebMvcConfigurationSupport{ @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); // 解决 doc.html 404 报错 registry.addResourceHandler("doc.html").addResourceLocations("classpath*:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath*:/META-INF/resources/webjars/"); } }
另外,也可以在啟動類別上進行實作重寫
@SpringBootApplication public class XXXApplication implements WebMvcConfigurer{ @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("doc.html").addResourceLocations("classpath*:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath*:/META-INF/resources/webjars/"); } }
造訪http:// 127.0.0.1:10086/doc.html,相較swagger-ui.html來說,此文件更為清爽。
swagger透過註解產生介面文檔,包括介面名稱、請求方法、參數、返回資訊等等。
1.1 @EnableSwagger2 開啟Swagger
作用於設定類別或啟動類別
#1.2 @EnableSwaggerBootstrapUI 開啟SwaggerBootstrapUi增強功能
作用於設定類或啟動類,若不使用增強功能,可不開啟。
2.1 @Api:修飾整個類,描述Controller的作用
value和tags皆為說明,可用tags代替value
@Api(value = "保险公司列表查询", tags = {"保险公司列表查询"})
2.2 @ApiOperation() 用於方法;表示一個http請求的操作
@ApiOperation(value = "信息员保存(注册)/更新", tags = {"信息員保存"}, notes = "messenger desc")
2.3 @ApiParam 用於方法,參數,欄位說明;表示對參數的新增元資料(說明或是否必填等)
適用於單一參數
@ApiParam(name="sdMessengerInfo",value="参数描述",required=true)
2.4 請求參數註解,可進行組合
#@ApiImplicitParams 用於方法,包含多個@ApiImplicitParam
@ApiImplicitParam 為方法,表示單獨的請求參數
適用於對多個參數進行描述
範例:
// 组合使用 @ApiImplicitParams ({ @ApiImplicitParam(name = "id", value = "参数中文描述", required = true) }) // 单独使用 @ApiImplicitParam(paramType="query", name="id", dataType="String", required=true, value="参数描述")
注意,當同時存在@ApiParam和@ApiImplicitParam時,以@ApiImplicitParam的描述為準。
2.5 @ApiIgnore() 用於類別或方法上,可以不被swagger顯示在頁面上 ,使用較少。
2.6 回應配置
@ApiResponses
@ApiResponse
// 单独配置 @ApiResponse(code = 400, message = "Invalid user supplied") // 组合使用 @ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
2.7 @ResponseHeader 回應頭設定
@ResponseHeader(name="head1",description="response head conf")
#3.1 @ApiModel 用於類別;表示對類別進行說明,用於參數以實體類別接收。
@ApiModel(value = "demo", description = "对象描述")
一般value和desc可以省略不寫
3.2 @ApiModelProperty 用於方法,欄位; 表示model屬性的說明或資料操作變更
@ApiModelProperty(value = "用户id",name = "openid2",dataType = "String", required = true, hidden = true)
value
–欄位說明
#name
–重寫屬性名稱
dataType
–重寫屬性類型
#required
–是否必填
以上是SpringBoot專案整合Swagger與swagger-bootstrap-ui及常用註解有哪些的詳細內容。更多資訊請關注PHP中文網其他相關文章!