Swagger&Knife4j教程

/ JAVA WEB / 1 条评论 / 6130浏览

SwaggerKnife4j

1. Swagger简介

号称世界上最流行的API接口框架，可以在线生成restful风格的api文档并支持文档的同步更新，可以直接运用在线测试api接口。支持多语言。

在前后台分离开发的背景下诞生的。

https://www.swagger.io

2. OpenAPI 是什么?

Open API 即开放 API，也称开放平台。 所谓的开放 API（OpenAPI）是服务型网站常见的一种应用，网站的服务商将自己的网站服务封装成一系列 API（Application Programming Interface，应用编程接口）开放出去，供第三方开发者使用，这种行为就叫做开放网站的 API，所开放的 API 就被称作 OpenAPI（开放 API ）。

Open API 规范可以使用YAML或者JSON格式进行编写。这样更利于我们和机器进行阅读。Open API规范为REST API定义了一个与语言无关的标准接口，允许人和计算机发现和理解服务的功能，无需访问源代码，文档或者通过流量检查。正确定义后消费者可以使用最少量的实现逻辑来理解远程服务并与之交互。

3. Swagger组件

Swagger是一个为围绕Open API规范构建的开源工具，可以帮助设计、构建、记录和使用REST API。

组件包括：

Swagger Editor：基于浏览器编辑器，可以在里面编写Open API规范。类似Markdown具有实时预览描述文件的功能。

Swagger UI：将Open API规范呈现为交互式API文档。用可视化UI展示描述文件。

Swagger Codegen：将OpenAPI规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同事也可以生成多种语言的客户端和服务端代码。

Swagger Inspector：和Swagger UI有点类型，但是可以返回更多信息，也会保存请求的实际参数数据。

Swagger Hub：集成了上面所有的项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

使用Swagger就是把相关的信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

4. Springfox

Springfox 利用自身的AOP特性，吧Swagger集成进来，底层还是Swagger。根据代码生成接口文档，所以正常的运行更新项目把那本，修改代码即可，而不需要跟着修改描述文件。我们在实际开发中都是直接使用springfox。

5. Swagger用法

@EnableSwagger2 是springfox提供的一个直接，代表开启swagger2。会扫描当前类所在包及之类中的所有的类型中的注解。做Swagger文档的定制。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

}

5.1 Swagger UI

image-20210519165911244

5.2 Swagger配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    
    @Bean
    Docket docket(Environment environment){
        Profiles dev = Profiles.of("dev");
        boolean isDev = environment.acceptsProfiles(dev);
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                //.enable(isDev)
                .select()
                //any()
                //none()
                //basePackage()
                //withClassAnnotation()
                //withMethodAnnotation()
               .apis(RequestHandlerSelectors.basePackage("info.huzd.ss.controller"))
                .paths(PathSelectors.ant("/api/**"))
                .build();
    }

    @Bean
    ApiInfo apiInfo(){
        Contact contact = new Contact("huzd","www.huzd.fun","huzd@si-tech.com.cn");
        return new ApiInfo("基础框架对外API接口文档",
                "该文档主要用于让开发人员能知道有哪些API接口可供调用。",
                "v1.0.0",
                "https://eip.teamshub.com",
                contact,"Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

5.3 自定义注解

withMethodAnnotation()

5.4 设置路径范围

  .paths(PathSelectors.ant("/api/**"))
    //这里面支持or and 等断言运算

6. 常用注解

6.1 @Api

类上注解。控制整个类生成接口信息的内容。

示例：

@RequestMapping("/api")
@Api(tags = {"default","用户管理"})
public class ApiController {

    @RequestMapping("/index")
    public String index(){
        return "index";
    }

    @GetMapping("/get")
    public String get(String username,String password){
        return "result-username:"+username+",password:"+password;
    }

    @PostMapping("/post")
    public String post(String age,String sex){
        return "result-age:"+age+",sex:"+sex;
    }
}
image-20210519172632032

6.2 @ApiOperation

标注在方法上。

    @RequestMapping("/index")
    @ApiOperation(value = "Api默认方法index",notes = "该方法主要用来测试的你懂我也懂！")
    public String index(){
        return "index";
    }

效果：

image-20210519173235381

6.3 @ApiParam

用来描述参数的相关api信息。

    @RequestMapping("/index")
    @ApiOperation(value = "Api默认方法index",notes = "该方法主要用来测试的你懂我也懂！")
    public String index(@ApiParam(name = "用户名",value="用户注册时的用户名",required = true,example = "admin")String username,
                        @ApiParam(name = "密码",value="用户注册时的密码",required = true,example = "123456")String password){
        return "index";
    }

效果：

image-20210519173817011

6.4 @ApiIgnore

标明当前API不包含该类、方法、参数等。作用域范围：该类、方法、参数

6.5 @ApiImplicitParams

@ApiImplicitParams & @ApiImplicitParam作用于方法上用来统一说明参数的信息。

代码：

    @GetMapping("/get")
    @ApiImplicitParams(value = {@ApiImplicitParam(name = "用户名",value="用户注册时的用户名",required = true,example = "admin"),
                                @ApiImplicitParam(name = "密码",value="用户注册时的密码",required = true,example = "123456")
    })
    public String get(String username,String password){
        return "result-username:"+username+",password:"+password;
    }

效果：

image-20210519174813771

6.6 @ApiModel

描述一个实体类型。这个实体类型如果成为任何一个生成api帮助文档方法的返回值类型的时候，此注解被解析。

@ApiModel(value = "狗类",description = "用来存储狗的特征属性")
public class Dog implements Serializable {
    @ApiModelProperty(name = "狗名",dataType = "字符型（String）",required = true,example = "hali")
    private String name;
    @ApiModelProperty(name = "狗年龄",dataType = "数值型（Integer）",required = true,example = "10")
    private Integer age;
  
}

image-20210519180404616

image-20210519180438383

image-20210519180449575

7. knife

讲真swagger ui的界面太丑了，于是我下意识的去网上找了一下有没有好看的界面。然后发现了knife。

我们先来从最原始的需求出发，我只想让API界面好看点。

7.1 替换SwaggerUI

如果我们仅仅想替换SwaggerUI，我们可以只引入knife4j-spring-ui （前身为swagger-bootstrap-ui），此时swaggerUI和knife UI是并存的可以同时访问。

<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-spring-ui</artifactId>
  <version>3.0.2</version>
</dependency>

效果：

访问地址，knife 默认访问地址是：http://${host}:${port}/doc.html

image-20210520094930604

7.2 Knife4j简介

knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案。 官方网址

Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一个纯swagger-ui的ui皮肤项目

7.3 如何使用Knife4j

7.3.1 引入maven

在pom.xml文件中加入maven引用：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

注意事项：

7.3.2 开启knife4j增强

@Configuration
@EnableSwagger2  //3.x版本的knife4j 已经放弃EnableSwagger2WebMvc 使用swagger原生的注解
public class SwaggerConfig {

    /*引入Knife4j提供的扩展类*/
    private final OpenApiExtensionResolver openApiExtensionResolver;

    @Autowired
    public SwaggerConfig(OpenApiExtensionResolver openApiExtensionResolver) {
        this.openApiExtensionResolver = openApiExtensionResolver;
    }

    @Bean
    Docket docket(Environment environment){

        Profiles dev = Profiles.of("dev");
        boolean isDev = environment.acceptsProfiles(dev);
        String groupName="2.X版本";
        return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
                //.enable(isDev)
                .groupName(groupName)
                .select()
                //any()
                //none()
                //basePackage()
                //withClassAnnotation()
                //withMethodAnnotation()
                .apis(RequestHandlerSelectors.basePackage("info.huzd.ss.controller"))
                .paths(PathSelectors.ant("/api/**"))
                .build()
          			//这里非常重要！是开启knife4j增强功能的关键！
                .extensions(openApiExtensionResolver.buildExtensions(groupName));
    }

    @Bean
    ApiInfo apiInfo(){
        Contact contact = new Contact("huzd","www.huzd.fun","huzd@si-tech.com.cn");
        return new ApiInfo("基础框架对外API接口文档",
                "该文档主要用于让开发人员能知道有哪些API接口可供调用。",
                "v1.0.0",
                "https://eip.teamshub.com",
                contact,"Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

效果：

image-20210520135734652

7.4 Knife4j 配置

各个配置属性说明如下：

属性默认值说明值
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.enableAfterScripttrue调试Tab是否显示AfterScript功能,默认开启
knife4j.setting.languagezh-CNUi默认显示语言,目前主要有两种:中文(zh-CN)、英文(en-US)
knife4j.setting.enableSwaggerModelstrue是否显示界面中SwaggerModel功能
knife4j.setting.swaggerModelNameSwagger Models重命名SwaggerModel名称,默认
knife4j.setting.enableDocumentManagetrue是否显示界面中"文档管理"功能
knife4j.setting.enableReloadCacheParameterfalse是否在每个Debug调试栏后显示刷新变量按钮,默认不显示
knife4j.setting.enableVersionfalse是否开启界面中对某接口的版本控制,如果开启，后端变化后Ui界面会存在小蓝点
knife4j.setting.enableRequestCachetrue是否开启请求参数缓存
knife4j.setting.enableFilterMultipartApisfalse针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址
knife4j.setting.enableFilterMultipartApiMethodTypePOST具体接口的过滤类型
knife4j.setting.enableHostfalse是否启用Host
knife4j.setting.enableHomeCustomfalse是否开启自定义主页内容
knife4j.setting.homeCustomLocation主页内容Markdown文件路径
knife4j.setting.enableSearchfalse是否禁用Ui界面中的搜索框
knife4j.setting.enableFootertrue是否显示Footer
knife4j.setting.enableFooterCustomfalse是否开启自定义Footer
knife4j.setting.footerCustomContentfalse自定义Footer内容
knife4j.setting.enableDynamicParameterfalse是否开启动态参数调试功能
knife4j.setting.enableDebugtrue启用调试
knife4j.setting.enableOpenApitrue显示OpenAPI规范
knife4j.setting.enableGrouptrue显示服务分组

本文由 huzd 创作，采用 知识共享署名4.0 国际许可协议进行许可本站文章除注明转载/出处外，均为本站原创或翻译，转载前请务必署名最后编辑时间
为: 2021/05/20 14:07

→ ← ↓ ↑
  1. huzd

    Hello

    回复
  1. 1