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:参数的默认值
- paramType:参数放在哪个地方
- @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
【推荐】国内首个AI IDE,深度理解中文开发场景,立即下载体验Trae
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· AI与.NET技术实操系列(二):开始使用ML.NET
· 记一次.NET内存居高不下排查解决与启示
· 探究高空视频全景AR技术的实现原理
· 理解Rust引用及其生命周期标识(上)
· 浏览器原生「磁吸」效果!Anchor Positioning 锚点定位神器解析
· 全程不用写代码,我用AI程序员写了一个飞机大战
· DeepSeek 开源周回顾「GitHub 热点速览」
· 记一次.NET内存居高不下排查解决与启示
· MongoDB 8.0这个新功能碉堡了,比商业数据库还牛
· .NET10 - 预览版1新功能体验(一)