网站后天添加文章不显示,保定专业做网站,夸克资源搜索引擎,已备案网站注册Swagger
课程目标
Swagger简介【了解】
Springboot整合swagger【掌握】
Swagger 常用注解【掌握】
knife4j-Swagger【会用】
一、Swagger3简介 Swagger 是一系列 RESTful API 的工具#xff0c;通过 Swagger 可以获得项目的⼀种交互式文档#xff0c;客户端 SDK 的自 动…Swagger
课程目标
Swagger简介【了解】
Springboot整合swagger【掌握】
Swagger 常用注解【掌握】
knife4j-Swagger【会用】
一、Swagger3简介 Swagger 是一系列 RESTful API 的工具通过 Swagger 可以获得项目的⼀种交互式文档客户端 SDK 的自 动生成等功能。Swagger 的目标是为 REST APIs 定义一个标准的、与语⾔言无关的接口使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。当服务通过 Swagger 定义消费者就能与远程的服务互动通过少量的实现逻辑。Swagger丝袜哥是世界上最流行的 API 表达工具。OpenAPI阶段的Swagger也被称为Swagger 3.0。在Swagger 2.0后Swagger规范正式更名为OpenAPI规范并且根据OpenAPI规范的版本号进行了更新。因此Swagger 3.0对应的就是OpenAPI 3.0版本它是Swagger在OpenAPI阶段推出的一个重要版本。与前几个版本相比Swagger 3.0更加强调对RESTful API的支持和规范化提供了更丰富和灵活的定义方式并且可以用于自动生成文档、客户端代码、服务器代码和测试工具等。
二、Springboot整合swagger3 使用 Spring Boot 集成 Swagger 的理念是使用用注解来标记出需要在 API 文档中展示的信息Swagger 会根据项目中标记的注解来生成对应的 API 文档。Swagger 被号称世界上最流行的 API 工具它提供了 API 管理的全套解决方案API 文档管理需要考虑的因素基本都包含这里将讲解最常用的定制内容。添加依赖 org.springdoc springdoc-openapi-starter-webmvc-ui 2.6.0 org.springdoc springdoc-openapi-starter-webmvc-api 2.6.0 创建 SwaggerConfig 配置类 /** * swagger3配置类 */ Configuration public class SwaggerConfig { Beanpublic OpenAPI openAPI(){return new OpenAPI().info(this.getInfo());}public Info getInfo(){return new Info().title(Springboot集成Swagger3) //标题.description(Springboot集成Swagger3接口说明) //项目描述.contact(new Contact().name(蜗牛学院)) //作者.version(V1.0); //版本号}
}访问swagger 启动项目后输入http://localhost:8080/swagger-ui/index.html 可看到swagger页面 如果在访问 /swagger-ui/index.html 时出现 404 。这是因为当你访问 .html 等静态资源时Spring MVC 默认是在你自己项目的 resources/static 目录下去找它们如果没有自然就是 404 。而 swagger 相关的 .html 等静态资源是在依赖包含的 swagger-ui 项目jar包 下。所以你需要通过静态资源配置来『告诉』Spring MVC 当收到 swagger 相关的静态资源访问时去对应的这个目录下找它们。 /** * spring mvc配置类 */ Configuration //项目启动时加载此类 public class WebMvcConfig implements WebMvcConfigurer { Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(“/swagger-ui/**”) .addResourceLocations(“classpath:/META-INF/resources/webjars/springfox-swagger-ui/”); } } 配置访问路径 swagger的访问路径可以自己更改 默认路径 springdoc: api-docs: path: /v3/api-docs swagger-ui: path: /swagger-ui.html #可以改成自己喜欢的路径如/doc.html
三、knife4j-Swagger
knife4j 是 Swagger 生成 API 文档的增强解决方案最主要是 knife4j 提供了动态字段注释功能实现 Map 来接收参数这个的接口文档生成忽略参数属性来实现同一个实体类对不同接口生成不同的文档添加依赖 前面swagger3的依赖不需要了 com.github.xiaoymin knife4j-openapi3-jakarta-spring-boot-starter 4.3.0 创建配置类 /** * swagger3配置类 */ Configuration public class SwaggerConfig { Bean public OpenAPI openAPI(){ return new OpenAPI().info(this.getInfo()); } public Info getInfo(){return new Info().title(Springboot集成Swagger3) //标题.description(Springboot集成Swagger3接口说明) //项目描述.contact(new Contact().name(蜗牛学院)) //作者.version(V1.0); //版本号}
}启动项目后通过http://127.0.0.1:8080/doc.html 访问knife4j页面
四、Swagger3 常用注解
Swagger 通过注解表明该接口会生成文档包括接口名、请求方法、参数、返回信息等。1、Tag
作用于类上一般用来对controller类进行说明
语法 Tag(name 用户接口, description 用户管理相关接口)示例
RestController
Tag(name用户操作)
public class UserController {}2、Operation
作用于Controller的方法上。用于对controller方法进行说明
语法
Operation(summary 操作摘要,description 操作的详细描述,operationId operationId,tags tag1,parameters {Parameter(name param1, description 参数1, required true),Parameter(name param2, description 参数2, required false)})示例 GetMapping(/user/list)Operation(summary 用户列表)public ListUser userList(){return userService.finUser();}参数说明
summary简短描述description 更详细的描述hidden是否隐藏tags标签用于分组APIoperationId操作的唯一标识符建议使用唯一且具有描述性的名称parameters指定相关的请求参数使用 Parameter 注解来定义参数的详细属性。requestBody指定请求的内容使用 RequestBody 注解來指定请求的类型。responses指定操作的返回内容使用 ApiResponse 注解定义返回值的详细属性。
3、Parameters
作用于Controller的方法上。Parameters注解中包含多个 Parameter 注解通过Parameter注解对controller方法中的非对象类型形参进行说明
语法
Parameters({Parameter(name param1,description description,required true,in ParameterIn.PATH,schema Schema(type string)),Parameter(name param2,description description,required true,in ParameterIn.QUERY,schema Schema(type integer))
})示例GetMapping(/user/query)Operation(summary 根据条件查询用户)Parameters({Parameter(nameusername,in ParameterIn.QUERY,description 用户名,required true,schema Schema(type String)),Parameter(nameage,in ParameterIn.QUERY,description 年龄,required true,schema Schema(type Integer))})public ListUser queryUser(RequestParam(value username,required true,defaultValue ) String username,RequestParam(value age,required true,defaultValue 0) Integer age){return userService.finUser();}Parameter参数说明
name : 指定的参数名in参数来源可选 query、header、path 或 cookie默认为空表示忽略ParameterIn.QUERY 请求参数ParameterIn.PATH 路径参数ParameterIn.HEADER header参数ParameterIn.COOKIE cookie 参数description参数描述required是否必填默认为 falseschema 参数的数据类型。如 schema Schema(type “string”)
4、ApiResponses
作用于Controller的方法上。ApiResponses包含多个ApiResponse。通过ApiResponse对controller方法的返回值进行说明
语法
ApiResponse(responseCode 200, description 查询成功,
content Content(schema Schema(implementation User.class)))
ApiResponse(responseCode 404, description 查询失败)示例GetMapping(/user/query)Operation(summary 根据条件查询用户)ApiResponses({ApiResponse(responseCode 2000,description 多条件查询成功,content Content(schema Schema(implementation List.class))),ApiResponse(responseCode 5000,description 多条件查询失败成功)})public ResponseResultListUser queryUser(){return new ResponseResult(2000,OK,null);}ApiResponse参数说明
responseCode响应的 HTTP 状态码description响应信息的描述content响应的内容
5、Schema
用于FO的类上。用于对controller中对象参数对应的FO对象的属性进行说明
vo实体类 Data Tag(name “用户Vo”, description “接收用户信息实体类”) public class UserVo implements Serializable { private static final long serialVersionUID 1L; Schema(name “id”, type “Integer”,description “用户id”,defaultValue “0”) private Integer id; Schema(name “username”, type “String”,description “用户真实姓名”,defaultValue “”) private String username; Schema(name “birthday”, type “LocalDateTime”,description “生日”,defaultValue “”) private LocalDateTime birthday; Schema(name “sex”, type “String”,description “性别”,defaultValue “男”) private String sex; } 参数说明 name名称 title标题 description描述 example示例值 required是否为必须 format属性的格式。如 Schema(format “email”) maxLength 、 minLength指定字符串属性的最大长度和最小长度 maximum 、 minimum指定数值属性的最大值和最小值 pattern指定属性的正则表达式模式 type 数据类型integerlongfloatdoublestringbytebinarybooleandatedateTimepassword必须是字符串。如 Schema(type“integer”) implementation 具体的实现类可以是类本身也可以是父类或实现的接口。controller PostMapping(“/user/add”) Operation(summary “添加用户”) public ResponseResultList addUser(RequestBody UserFo userFo){ return new ResponseResult(2000,“OK”,null); }
五、spring security放行swagger3
修改security配置类 /*** spring security过滤器链配配置* param http* return* throws Exception*/Beanpublic SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception{//鉴权配置http.authorizeHttpRequests(authorizeHttpRequests-authorizeHttpRequests//允许所有的OPTIONS请求.requestMatchers(HttpMethod.OPTIONS,/**).permitAll()//放行swagger3.requestMatchers(HttpMethod.GET,/v3/api-docs/**,/doc.html,/webjars/**).permitAll().anyRequest().authenticated());//认证配置http.formLogin().successHandler(simpleAuthenticationSuccessHandler) //认证成功后的处理器.failureHandler(simpleAuthenticationFailureHandler) //认证失败后的处理器.permitAll();//这句配置很重要新手容易忘记。放开 login.html和dologin 的访问权//退出操作配置http.logout().logoutSuccessHandler(simpLogoutSuccessHandler);//将自定义的jwtFilter添加到Spring Security过滤器链的倒数第二个以前http.addFilterAfter(jwtFilter, UsernamePasswordAuthenticationFilter.class);//认证和鉴权异常配置http.exceptionHandling().authenticationEntryPoint(simpleAuthenticationEntryPoint) //认证异常处理器.accessDeniedHandler(simpleAccessDeniedHandler); //鉴权异常处理器//前后端项目中要禁用掉sessionhttp.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);//关闭crsf 跨域漏洞防御http.csrf(csrf- csrf.disable());return http.build();}
文章转载自： http://www.morning.dhxnr.cn.gov.cn.dhxnr.cn http://www.morning.hrjrt.cn.gov.cn.hrjrt.cn http://www.morning.nrbqf.cn.gov.cn.nrbqf.cn http://www.morning.rqbkc.cn.gov.cn.rqbkc.cn http://www.morning.tmnyj.cn.gov.cn.tmnyj.cn http://www.morning.tngdn.cn.gov.cn.tngdn.cn http://www.morning.jklns.cn.gov.cn.jklns.cn http://www.morning.zfrs.cn.gov.cn.zfrs.cn http://www.morning.rntby.cn.gov.cn.rntby.cn http://www.morning.clwhf.cn.gov.cn.clwhf.cn http://www.morning.rlbg.cn.gov.cn.rlbg.cn http://www.morning.ghjln.cn.gov.cn.ghjln.cn http://www.morning.srrzb.cn.gov.cn.srrzb.cn http://www.morning.zdtfr.cn.gov.cn.zdtfr.cn http://www.morning.snzgg.cn.gov.cn.snzgg.cn http://www.morning.mtzyr.cn.gov.cn.mtzyr.cn http://www.morning.fthcq.cn.gov.cn.fthcq.cn http://www.morning.rnsjp.cn.gov.cn.rnsjp.cn http://www.morning.trwkz.cn.gov.cn.trwkz.cn http://www.morning.wjjxr.cn.gov.cn.wjjxr.cn http://www.morning.lmmh.cn.gov.cn.lmmh.cn http://www.morning.dpwcl.cn.gov.cn.dpwcl.cn http://www.morning.yhtnr.cn.gov.cn.yhtnr.cn http://www.morning.xhpnp.cn.gov.cn.xhpnp.cn http://www.morning.sbrjj.cn.gov.cn.sbrjj.cn http://www.morning.dsprl.cn.gov.cn.dsprl.cn http://www.morning.fssmx.com.gov.cn.fssmx.com http://www.morning.pqqhl.cn.gov.cn.pqqhl.cn http://www.morning.pmjhm.cn.gov.cn.pmjhm.cn http://www.morning.fhqdb.cn.gov.cn.fhqdb.cn http://www.morning.swlwf.cn.gov.cn.swlwf.cn http://www.morning.nhpmn.cn.gov.cn.nhpmn.cn http://www.morning.rzmsl.cn.gov.cn.rzmsl.cn http://www.morning.cwlxs.cn.gov.cn.cwlxs.cn http://www.morning.wwjft.cn.gov.cn.wwjft.cn http://www.morning.gthgf.cn.gov.cn.gthgf.cn http://www.morning.tmfm.cn.gov.cn.tmfm.cn http://www.morning.ntcmrn.cn.gov.cn.ntcmrn.cn http://www.morning.elmtw.cn.gov.cn.elmtw.cn http://www.morning.rkdzm.cn.gov.cn.rkdzm.cn http://www.morning.fktlr.cn.gov.cn.fktlr.cn http://www.morning.zlff.cn.gov.cn.zlff.cn http://www.morning.bswnf.cn.gov.cn.bswnf.cn http://www.morning.qkqhr.cn.gov.cn.qkqhr.cn http://www.morning.mhlkc.cn.gov.cn.mhlkc.cn http://www.morning.rqhbt.cn.gov.cn.rqhbt.cn http://www.morning.ptzf.cn.gov.cn.ptzf.cn http://www.morning.lnbyk.cn.gov.cn.lnbyk.cn http://www.morning.qgxnw.cn.gov.cn.qgxnw.cn http://www.morning.pghry.cn.gov.cn.pghry.cn http://www.morning.xplng.cn.gov.cn.xplng.cn http://www.morning.dqzcf.cn.gov.cn.dqzcf.cn http://www.morning.fqljq.cn.gov.cn.fqljq.cn http://www.morning.pcngq.cn.gov.cn.pcngq.cn http://www.morning.fkmrj.cn.gov.cn.fkmrj.cn http://www.morning.bmfqg.cn.gov.cn.bmfqg.cn http://www.morning.wslpk.cn.gov.cn.wslpk.cn http://www.morning.dycbp.cn.gov.cn.dycbp.cn http://www.morning.jwqqd.cn.gov.cn.jwqqd.cn http://www.morning.srrrz.cn.gov.cn.srrrz.cn http://www.morning.qstjr.cn.gov.cn.qstjr.cn http://www.morning.pkmcr.cn.gov.cn.pkmcr.cn http://www.morning.snbry.cn.gov.cn.snbry.cn http://www.morning.rgsnk.cn.gov.cn.rgsnk.cn http://www.morning.kaoshou.net.gov.cn.kaoshou.net http://www.morning.tqjwx.cn.gov.cn.tqjwx.cn http://www.morning.nxfwf.cn.gov.cn.nxfwf.cn http://www.morning.ynryz.cn.gov.cn.ynryz.cn http://www.morning.ampingdu.com.gov.cn.ampingdu.com http://www.morning.kongpie.com.gov.cn.kongpie.com http://www.morning.gnwpg.cn.gov.cn.gnwpg.cn http://www.morning.glwyn.cn.gov.cn.glwyn.cn http://www.morning.rmxwm.cn.gov.cn.rmxwm.cn http://www.morning.wkpfm.cn.gov.cn.wkpfm.cn http://www.morning.redhoma.com.gov.cn.redhoma.com http://www.morning.pwzzk.cn.gov.cn.pwzzk.cn http://www.morning.kzslk.cn.gov.cn.kzslk.cn http://www.morning.aswev.com.gov.cn.aswev.com http://www.morning.thbkc.cn.gov.cn.thbkc.cn http://www.morning.wdply.cn.gov.cn.wdply.cn
