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", "33381993@qq.com");
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

posted @   生生灯火半杯月  阅读(3079)  评论(0编辑  收藏  举报
编辑推荐:
· AI与.NET技术实操系列(二):开始使用ML.NET
· 记一次.NET内存居高不下排查解决与启示
· 探究高空视频全景AR技术的实现原理
· 理解Rust引用及其生命周期标识(上)
· 浏览器原生「磁吸」效果!Anchor Positioning 锚点定位神器解析
阅读排行:
· 全程不用写代码,我用AI程序员写了一个飞机大战
· DeepSeek 开源周回顾「GitHub 热点速览」
· 记一次.NET内存居高不下排查解决与启示
· MongoDB 8.0这个新功能碉堡了,比商业数据库还牛
· .NET10 - 预览版1新功能体验(一)
点击右上角即可分享
微信分享提示