课程目标

定义一个标准的、与语⾔言无关的接口使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下能发现和理解各种服务的功能。

当服务通过

Swagger

定义消费者就能与远程的服务互动通过少量的实现逻辑。

Swagger丝袜哥是世界上最流行的

API

表达工具。

OpenAPI阶段的Swagger也被称为Swagger

2.0后Swagger规范正式更名为OpenAPI规范并且根据OpenAPI规范的版本号进行了更新。

因此Swagger

3.0版本它是Swagger在OpenAPI阶段推出的一个重要版本。

与前几个版本相比Swagger

3.0更加强调对RESTful

API的支持和规范化提供了更丰富和灵活的定义方式并且可以用于自动生成文档、客户端代码、服务器代码和测试工具等。

Spring

文档管理需要考虑的因素基本都包含这里将讲解最常用的定制内容。

添加依赖

org.springdoc

springdoc-openapi-starter-webmvc-ui

2.6.0

springdoc-openapi-starter-webmvc-api

2.6.0

OpenAPI().info(this.getInfo());}public

Info

Info().title(Springboot集成Swagger3)

//标题.description(Springboot集成Swagger3接口说明)

//项目描述.contact(new

启动项目后输入http://localhost:8080/swagger-ui/index.html

如果在访问

addResourceHandlers(ResourceHandlerRegistry

registry)

registry.addResourceHandler(“/swagger-ui/**”)

.addResourceLocations(“classpath:/META-INF/resources/webjars/springfox-swagger-ui/”);

配置访问路径

来接收参数这个的接口文档生成忽略参数属性来实现同一个实体类对不同接口生成不同的文档添加依赖

com.github.xiaoymin

knife4j-openapi3-jakarta-spring-boot-starter

4.3.0

OpenAPI().info(this.getInfo());

public

Info().title(Springboot集成Swagger3)

//标题.description(Springboot集成Swagger3接口说明)

//项目描述.contact(new

}启动项目后通过http://127.0.0.1:8080/doc.html

访问knife4j页面

通过注解表明该接口会生成文档包括接口名、请求方法、参数、返回信息等。

1、Tag

Tag(name

作用于Controller的方法上。

用于对controller方法进行说明

Operation(summary

GetMapping(/user/list)Operation(summary

用户列表)public

更详细的描述hidden是否隐藏tags标签用于分组APIoperationId操作的唯一标识符建议使用唯一且具有描述性的名称parameters指定相关的请求参数使用

Parameter

注解来定义参数的详细属性。

requestBody指定请求的内容使用

RequestBody

注解來指定请求的类型。

responses指定操作的返回内容使用

ApiResponse

作用于Controller的方法上。

Parameters注解中包含多个

Parameter

注解通过Parameter注解对controller方法中的非对象类型形参进行说明

param1,description

})示例GetMapping(/user/query)Operation(summary

根据条件查询用户)Parameters({Parameter(nameusername,in

用户名,required

userService.finUser();}Parameter参数说明

name

cookie默认为空表示忽略ParameterIn.QUERY

请求参数ParameterIn.PATH

参数description参数描述required是否必填默认为

falseschema

作用于Controller的方法上。

ApiResponses包含多个ApiResponse。

通过ApiResponse对controller方法的返回值进行说明

200,

查询失败)示例GetMapping(/user/query)Operation(summary

根据条件查询用户)ApiResponses({ApiResponse(responseCode

2000,description

List.class))),ApiResponse(responseCode

5000,description

ResponseResult(2000,OK,null);}ApiResponse参数说明

HTTP

状态码description响应信息的描述content响应的内容

5、Schema

用于FO的类上。

用于对controller中对象参数对应的FO对象的属性进行说明

vo实体类

数据类型integerlongfloatdoublestringbytebinarybooleandatedateTimepassword必须是字符串。

如

implementation

具体的实现类可以是类本身也可以是父类或实现的接口。

controller

Operation(summary

ResponseResult(2000,“OK”,null);

五、spring

securityFilterChain(HttpSecurity

http)

Exception{//鉴权配置http.authorizeHttpRequests(authorizeHttpRequests-authorizeHttpRequests//允许所有的OPTIONS请求.requestMatchers(HttpMethod.OPTIONS,/**).permitAll()//放行swagger3.requestMatchers(HttpMethod.GET,/v3/api-docs/**,/doc.html,/webjars/**).permitAll().anyRequest().au***nticated());//认证配置http.formLogin().successHandler(simpleAu***nticationSuccessHandler)

//认证成功后的处理器.failureHandler(simpleAu***nticationFailureHandler)

//认证失败后的处理器.permitAll();//这句配置很重要新手容易忘记。

放开

login.html和dologin

的访问权//退出操作配置http.logout().logoutSuccessHandler(simpLogoutSuccessHandler);//将自定义的jwtFilter添加到Spring

Security过滤器链的倒数第二个以前http.addFilterAfter(jwtFilter,

UsernamePasswordAu***nticationFilter.class);//认证和鉴权异常配置http.exceptionHandling().au***nticationEntryPoint(simpleAu***nticationEntryPoint)

//认证异常处理器.accessDeniedHandler(simpleAccessDeniedHandler);

//鉴权异常处理器//前后端项目中要禁用掉sessionhttp.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);//关闭crsf

http.build();}