打广告型的营销网站,网站域名 没有续费,网站制作公司天强科技,嵌入式开发板推荐在开发微服务应用时#xff0c;API 文档的生成和维护是非常重要的一环。Swagger 是一个非常流行的 API 文档工具#xff0c;可以帮助我们自动生成 RESTful API 的文档#xff0c;并提供了一个友好的界面供开发者测试 API。本文将介绍如何在 Spring Boot 项目中集成 Knife4j …在开发微服务应用时API 文档的生成和维护是非常重要的一环。Swagger 是一个非常流行的 API 文档工具可以帮助我们自动生成 RESTful API 的文档并提供了一个友好的界面供开发者测试 API。本文将介绍如何在 Spring Boot 项目中集成 Knife4j 的 Swagger以实现 API 文档的自动生成和展示。
官网Knife4j · 集Swagger2及OpenAPI3为一体的增强解决方案. | Knife4j
源码knife4j: Knife4j是一个集Swagger2 和 OpenAPI3为一体的增强解决方案
1. UI 界面配置步骤
1.1. 添加依赖
dependencygroupIdcom.github.xiaoymin/groupIdartifactIdknife4j-spring-boot-starter/artifactIdversion3.0.2/version
/dependency
1.2. 添加配置文件
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;Configuration
Slf4j
public class WebMvcConfiguration extends WebMvcConfigurationSupport {/*** 该方法的主要作用是通过knife4j生成接口文档若想要多个分组则需要配置多个Docket实例** return Docket 实例用于Swagger接口文档的配置和生成*/Beanpublic Docket docket(Environment environment) {// 构建API信息用于Swagger文档的元数据ApiInfo apiInfo new ApiInfoBuilder().title(swagger测试项目接口文档) // 设置API的标题.contact(new Contact(zjp, http://termurl.com, zjpemail.com)).version(1.0) // 设置API的版本.description(swagger测试项目接口文档) // 设置API的描述信息.termsOfServiceUrl(http://termurl.com) // 设置服务条款URL非必要.license(Apache 2.0) // 设置API的授权协议非必要.licenseUrl(http://www.apache.org/licenses/LICENSE-2.0) // 设置授权协议的URL非必要.build();// 创建Docket实例并进行配置Docket docket new Docket(DocumentationType.SWAGGER_2) // 指定文档类型为Swagger2。支持SWAGGER_121.2版本、SWAGGER_22.0版本、OAS_303.0版本等。多个实例版本不同会在各个版本中各生成一个文档.enable(environment.acceptsProfiles(Profiles.of(dev, test))) // 设置是否启用Swagger默认为true也可以通过环境变量或配置文件来动态控制.apiInfo(apiInfo) // 设置API信息.select() // 进入配置选择器// 若需要匹配指定包路径的控制器可以使用basePackage()方法可以是包名或类名支持通配符*// 若需要匹配所有路径可以使用any()方法例如any();// 若需要匹配指定注解的控制器可以使用withClassAnnotation()方法例如withClassAnnotation(RestController.class);// 若需要匹配指定方法注解的控制器可以使用withMethodAnnotation()方法例如withMethodAnnotation(ApiOperation.class);// 若不需要匹配任何注解的控制器可以使用none()方法例如none();.apis(RequestHandlerSelectors.basePackage(com.zjp.knife4jswaggerdemo.controller))// 若需要匹配指定类可以使用any()方法例如any();// 若需要匹配指定路径可以使用ant()方法例如ant(/api/**);// 若需要排除某些路径可以使用ant()方法例如ant(!/api/**);// 若需要匹配以指定字符串结尾的路径可以使用ant()方法例如ant(/**/api);// 若需要匹配以指定字符串开头的路径可以使用regex()方法例如regex(/api/.*);// 若不需要匹配任何路径可以使用none()方法例如none().paths(PathSelectors.any()).build() // 结束配置并构建Docket实例.groupName(default); // 设置分组名称多个分组名称不能重名
// .pathMapping(/) // 设置路径映射用于指定Swagger UI的根路径默认为/。
// .protocols(new HashSet(Arrays.asList(http, https))) // 设置支持的协议
// .securitySchemes(Collections.singletonList(new ApiKey(token, HttpHeaders.AUTHORIZATION, In.HEADER.toValue()))) // 授权信息设置必要的header token等认证信息
// .securityContexts(Collections.singletonList(
// SecurityContext.builder()
// .securityReferences(Collections.singletonList(new SecurityReference(token, new AuthorizationScope[]{new AuthorizationScope(global, )})))
// .build())); // 设置全局安全上下文用于指定全局的授权信息return docket;}/*** 该方法的主要作用是通过knife4j生成接口文档若想要多个分组则需要配置多个Docket实例* 例如配置第二个Docket实例分组名称为api** return Docket 实例用于Swagger接口文档的配置和生成*/Beanpublic Docket docket1() {// 构建API信息用于Swagger文档的元数据ApiInfo apiInfo new ApiInfoBuilder().title(swagger测试项目接口文档).version(1.0).description(swagger测试项目接口文档).build();// 创建Docket实例并进行配置Docket docket new Docket(DocumentationType.SWAGGER_2).enable(true).apiInfo(apiInfo) // 设置API信息.select() // 进入配置选择器.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)).paths(PathSelectors.ant(/api/**)).build().groupName(api);return docket;}/*** 该方法用于在Spring MVC中配置静态资源的访问路径和位置* 它通过ResourceHandlerRegistry对象来注册资源处理器* 从而使得特定URL路径下的请求能够映射到应用程序的静态资源上** param registry ResourceHandlerRegistry实例用于注册资源处理器*/protected void addResourceHandlers(ResourceHandlerRegistry registry) {// 映射/doc.html到classpath:/META-INF/resources/以便访问该路径时能够获取到相应的静态文件registry.addResourceHandler(/doc.html).addResourceLocations(classpath:/META-INF/resources/);// 映射/webjars/**到classpath:/META-INF/resources/webjars/用于支持webjars资源的访问registry.addResourceHandler(/webjars/**).addResourceLocations(classpath:/META-INF/resources/webjars/);}
}
1.3. 启动测试
浏览器访问 http://localhost:8080/doc.html 访问结果如下图 界面说明
左上角的下拉框对应的分组如下图所示 主页对应的是 ApiInfo 里的信息及 Docket 里的 groupName 。 在文档管理-全局参数设置可以设置全局请求头和参数。 2. 使用swagger
2.1. 常用注解 注解 用途 示例 Api 标记一个控制器类描述该类的功能 Api(value 用户管理相关接口, tags {用户管理}) ApiOperation 描述一个 API 接口的方法 ApiOperation(value 获取用户信息, notes 根据用户ID获取用户信息) ApiParam 描述方法参数 ApiParam(name id, value 用户ID, required true) ApiImplicitParam 描述隐式参数常用于 GET 请求的查询参数 ApiImplicitParam(name token, value 访问令牌, required true, dataType string, paramType header) ApiImplicitParams 描述多个隐式参数 ApiImplicitParams({ ApiImplicitParam(name token, value 访问令牌, required true, dataType string, paramType header), ApiImplicitParam(name page, value 页码, required false, dataType integer, paramType query) }) ApiResponse 描述方法的响应信息 ApiResponse(code 200, message 成功返回用户信息) ApiResponses 描述多个响应信息 ApiResponses({ ApiResponse(code 200, message 成功返回用户信息), ApiResponse(code 404, message 用户不存在) }) ApiModel 描述一个模型类 ApiModel(description 用户信息) ApiModelProperty 描述模型类的属性 ApiModelProperty(主键值) ApiIgnore 忽略某个方法或类不生成 API 文档 ApiIgnore ApiExample 描述 API 示例请求 ApiExample(value 获取用户信息示例, source GET /users/{id})
2.2. 使用示例
controller层使用示例
import com.zjp.knife4jswaggerdemo.pojo.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;RestController
Api(value 用户管理相关接口, tags {用户管理})
public class UserController {GetMapping(/getUser)ApiOperation(value 获取用户信息, notes 根据用户ID获取用户信息)ApiImplicitParams({ApiImplicitParam(name token, value 访问令牌, required true, dataType string, paramType header),ApiImplicitParam(name page, value 页码, required false, dataType integer, paramType query)})ApiResponses({ApiResponse(code 200, message 成功返回用户信息),ApiResponse(code 404, message 用户不存在)})public User getUser(ApiParam(name id, value 用户ID, required true) RequestParam Integer id) {User user new User();user.setId(1);user.setName(Alice);user.setAge(18);user.setSex(female);return user;}
} 实体类使用示例
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;Data
ApiModel(value 用户信息, description 用户信息实体类)
public class User {ApiModelProperty(value 主键值, example 1001)private Integer id;ApiModelProperty(value 名称, example Bob)private String name;ApiModelProperty(value 年龄, example 32)private Integer age;ApiModelProperty(value 性别, example male)private String sex;
}
2.3. 启动测试
浏览器访问 http://localhost:8080/doc.html 访问结果如下图 实体类信息如下不调用实体类这里不会展示实体类信息 接口文档 测试接口 3. 其他配置
属性默认值说明值knife4j.enablefalse是否开启Knife4j增强模式knife4j.corsfalse是否开启一个默认的跨域配置,该功能配合自定义Host使用knife4j.productionfalse是否开启生产环境保护策略,详情参考文档knife4j.basic对Knife4j提供的资源提供BasicHttp校验,保护文档knife4j.basic.enablefalse关闭BasicHttp功能knife4j.basic.usernamebasic用户名knife4j.basic.passwordbasic密码knife4j.documents自定义文档集合该属性是数组knife4j.documents.group所属分组knife4j.documents.name类似于接口中的tag,对于自定义文档的分组knife4j.documents.locationsmarkdown文件路径,可以是一个文件夹(classpath:markdowns/*)也可以是单个文件(classpath:md/sign.md)knife4j.setting前端Ui的个性化配置属性knife4j.setting.enable-after-scripttrue调试Tab是否显示AfterScript功能,默认开启knife4j.setting.languagezh-CNUi默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US)knife4j.setting.enable-swagger-modelstrue是否显示界面中SwaggerModel功能knife4j.setting.swagger-model-nameSwagger Models重命名SwaggerModel名称,默认knife4j.setting.enable-document-managetrue是否显示界面中文档管理功能knife4j.setting.enable-reload-cache-parameterfalse是否在每个Debug调试栏后显示刷新变量按钮,默认不显示knife4j.setting.enable-versionfalse是否开启界面中对某接口的版本控制,如果开启后端变化后Ui界面会存在小蓝点knife4j.setting.enable-request-cachetrue是否开启请求参数缓存knife4j.setting.enable-filter-multipart-apisfalse针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址knife4j.setting.enable-filter-multipart-api-method-typePOST具体接口的过滤类型knife4j.setting.enable-hostfalse是否启用Hostknife4j.setting.enable-host-textfalseHOST地址knife4j.setting.enable-home-customfalse是否开启自定义主页内容knife4j.setting.home-custom-path主页内容Markdown文件路径knife4j.setting.enable-searchfalse是否禁用Ui界面中的搜索框knife4j.setting.enable-footertrue是否显示Footerknife4j.setting.enable-footer-customfalse是否开启自定义Footerknife4j.setting.footer-custom-contentfalse自定义Footer内容knife4j.setting.enable-dynamic-parameterfalse是否开启动态参数调试功能knife4j.setting.enable-debugtrue启用调试knife4j.setting.enable-open-apitrue显示OpenAPI规范knife4j.setting.enable-grouptrue显示服务分组
3.1. 访问权限控制
对应官网原文3.5 访问权限控制 | Knife4j
3.1.1. 生产环境禁用
目前Springfox-Swagger以及Knife4j提供的资源接口包括如下
资源说明/doc.htmlKnife4j提供的文档访问地址/v2/api-docs-extKnife4j提供的增强接口地址,自2.0.6版本后删除/swagger-resourcesSpringfox-Swagger提供的分组接口/v2/api-docsSpringfox-Swagger提供的分组实例详情接口/swagger-ui.htmlSpringfox-Swagger提供的文档访问地址/swagger-resources/configuration/uiSpringfox-Swagger提供/swagger-resources/configuration/securitySpringfox-Swagger提供 springdoc以及Knife4j提供的资源接口包括如下
资源说明/doc.htmlKnife4j提供的文档访问地址/v3/api-docsspringdoc提供的实例接口/v3/api-docs/swagger-configspringdoc提供的分组接口/v3/api-docs/**分组/swagger-ui/index.htmlspringdoc提供的文档访问地址
当我们部署系统到生产系统,为了接口安全,需要屏蔽所有Swagger的相关资源
如果使用SpringBoot框架,只需在application.properties或者application.yml配置文件中配置
knife4j:# 开启增强配置 enable: true# 开启生产环境屏蔽production: true 配置此属性后,所有资源都会屏蔽输出.
效果图如下 3.1.2. 登录认证
不管是官方的swagger-ui.html或者doc.html,目前接口访问都是无需权限即可访问接口文档的,很多朋友以前问我能不能提供一个登陆界面的功能,开发者输入用户名和密码来控制界面的访问,只有知道用户名和密码的人才能访问此文档
做登录页控制需要有用户的概念,所以相当长一段时间都没有提供此功能
针对Swagger的资源接口,Knife4j提供了简单的Basic认证功能
效果图如下 允许开发者在配置文件中配置一个静态的用户名和密码,当对接者访问Swagger页面时,输入此配置的用户名和密码后才能访问Swagger文档页面,如果您使用SpringBoot开发,则只需在相应的application.properties或者application.yml中配置如下
knife4j:# 开启增强配置 enable: true# 开启Swagger的Basic认证功能,默认是falsebasic:enable: true# Basic认证用户名username: test# Basic认证密码password: 123
如果用户开启了basic认证功能,但是并未配置用户名及密码,Knife4j提供了默认的用户名和密码
admin/123321 3.2. 请求参数缓存
在默认情况下,在接口调试的情况下,Knifetj对于接口的请求参数都会缓存起来该配置可以在前端界面中的个性化设置中看到,如下图 缓存的情况只会在后端没有给属性example的情况下产生,如果后端在写Swagger的注解的时候,给每个字段赋予了example的值,那么,Knife4j不会使用调试时缓存的值,而是会一直使用后端的example值。
当然开发者也可以在后端控制文档的接口调试功能针对请求后的参数是否需要缓存(自2.0.6版本开始)
yml配置如下
knife4j:enable: truesetting:# 对于调试中的请求参数是否缓存进行开启配置该参数默认为trueenable-request-cache: true 也可以手动清理缓存 3.3. 动态请求参数
方式一后台开启
开发者也可以通过开启Knife4j的增强配置进行默认开启配置如下
knife4j:enable: truesetting:# 开启动态请求参数true-开启false-关闭enable-dynamic-parameter: true
方式二界面开启 当在配置中勾选该选项后,我们的接口栏会有变化,如下图 在原本已存在的参数栏下会出现一栏空的参数栏,开发者可以输入参数名称、参数值对参数进行添加
不管是参数名称的变化还是参数值的变化,变化后会自动追加一行新的调试栏参数,效果图如下
