Swagger-常用配置-注解-問題

一、常用配置

不同版本的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", "[e-mail]");
        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：參數的默認值
• @ApiResponses：用於表示一組響應
• @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
  • code：數字，例如400
  • message：信息，例如"請求參數沒填好"
  • response：拋出異常的類
• @ApiModel：描述一個Model的信息（這種一般用在post創建的時候，使用@RequestBody這樣的場景，請求參數無法使用@ApiImplicitParam注解進行描述的時候）
  • @ApiModelProperty：描述一個model的屬性

三、常見問題

1、資源訪問的問題：並非必要且靈活配置

@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/");

    }
}

2、No API ...Swagger Cannot read property 'url' of undefined

檢測controller中各個方法的注解是否規范使用；
如：@ApiImplicitParam在@ApiImplicitParams外邊

3、Unresolvable class definition for class [springfox.documentation.spring.web.

版本沖突，可能有多個Swagger依賴包，需要排除

最后當然還有界面更好的Knife4j

https://blog.csdn.net/weixin_44183847/article/details/119252171