Swagger-常用配置-註解-問題
阿新 • • 發佈:2021-12-15
一、常用配置
不同版本的Swagger配置略有不同
Swagger2.9版本
訪問地址:http://localhost:8080/swagger-ui.html
SwaggerConfig:
@Configuration // 作為配置類應有的註解 @EnableSwagger2 // 開啟Swagger2 public class SwaggerConfig { @Bean public Docket docket(Environment environment){ // 設定要顯示的Swagger環境 Profiles dev = Profiles.of("dev","test"); // environment.acceptsProfiles判斷是否處在自己設定的環境中 // 如果當前的環境是dev就是true boolean flag = environment.acceptsProfiles(dev); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(flag) // 判斷是否合適開啟Swagger .select() .apis(RequestHandlerSelectors.basePackage("com.du.controller")) .paths(PathSelectors.ant("/hello/**")) .build(); } public ApiInfo apiInfo(){ Contact contact = new Contact("漁舟唱晚", "du.com", "[email protected]"); return new ApiInfo( "Api Documentation-Swagger", // 標題,ui介面的名稱 "Api Documentation", // 描述 "1.0", // 版本 "urn:tos", // 組織域名 contact, // 作者資訊 "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } }
多個組:及多個@Bean,Docket
Swagger3.0版本
訪問地址:http://localhost:8080/swagger-ui/index.html
SwaggerConfig:
@Configuration @EnableOpenApi public class SwaggerConfig { @Bean(value = "swaggerRestApi") public Docket swaggerRestApi(Environment environment) { // 要顯示的Swagger環境 Profiles dev = Profiles.of("dev","test"); // 判斷是否在自己的環境中 boolean flag = environment.acceptsProfiles(dev); ApiInfo apiInfo= new ApiInfoBuilder() .title("介面文件") .description("介面文件") .version("1.0.0") .contact(new Contact("CZ", "http://www.**.com", "**@mail.com")) .license("Apache 2.0") .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html") .build(); return new Docket(DocumentationType.SWAGGER_2) .select() .apis(RequestHandlerSelectors.basePackage("com.du.controller")) .paths(PathSelectors.any()) .build() .groupName("介面文件") .apiInfo(apiInfo) .enable(flag); } }
二、常用註解
- @Api:用在類上,說明該類的作用
- @ApiOperation:用在方法上,說明方法的作用
- @ApiImplicitParams:用在方法上包含一組引數說明
- @ApiImplicitParam:用在@ApiImplicitParams註解中,指定一個請求引數的各個方面
- paramType:引數放在哪個地方
- header-->請求引數的獲取:@RequestHeader
- query-->請求引數的獲取:@RequestParam
- path(用於restful介面)-->請求引數的獲取:@PathVariable
- body(不常用)
- form(不常用)
- name:引數名
- dataType:引數型別
- required:引數是否必須傳
- value:引數的意思
- defaultValue:引數的預設值
- paramType:引數放在哪個地方
- @ApiResponses:用於表示一組響應
- @ApiResponse:用在@ApiResponses中,一般用於表達一個錯誤的響應資訊
- code:數字,例如400
- message:資訊,例如"請求引數沒填好"
- response:丟擲異常的類
- @ApiModel:描述一個Model的資訊(這種一般用在post建立的時候,使用@RequestBody這樣的場景,請求引數無法使用@ApiImplicitParam註解進行描述的時候)
- @ApiModelProperty:描述一個model的屬性
三、常見問題
資源訪問的問題:並非必要且靈活配置
@Configuration
public class SwaggerWebMvcConfig extends WebMvcConfigurerAdapter {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
No API ...Swagger Cannot read property 'url' of undefined
檢測controller中各個方法的註解是否規範使用;
如:@ApiImplicitParam在@ApiImplicitParams外邊
最後當然還有介面更好的Knife4j
https://blog.csdn.net/weixin_44183847/article/details/119252171