Swagger以及knife4j的基本使用

目录

• Swagger以及knife4j基本使用
  
  
  
  • Swagger 介绍：
    
    
    
    • RESTful 面向资源
      
    • SpringBoot使用swagger
      
    
    
  • Knife4j --Swagger增强工具
    
  
  

Swagger以及knife4j基本使用


Swagger 介绍：

官网：https://swagger.io/

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的 Web 服务

RESTful 面向资源

RESTful是一种架构的规范与约束、原则，符合这种规范的架构就是RESTful架构

Rest是web服务的一种架构风格；使用HTTP，URI，XML，JSON，HTML等广泛流行的标准和协议；轻量级，跨平台，跨语言的架构设计，它是一种设计风格，不是一种标准，是一种思想。

说明：
http方法资源操作幂等安全GETSELECT是是POSTINSERT否否PUTUPDATE是否DELETEDELETE是否

幂等性：对同一REST接口多次访问，得到的资源状态是相同的
安全性：对该REST接口访问，不会使服务端资源状态发生改变

优点：

• 透明性 --暴露资源存在（资源操作通过http本身语义进行描述，不用单独描述）
  
• 充分利用HTTP协议本身语义
  
• 无状态 --在调用一个接口时可以不用考虑上下文，不用考虑当前状态降低了复杂度
  
• HTTP本身提供了丰富的内容协商手段（缓存，资源修改的乐观并发控制等可以通过与业务无关的中间件实现）
  

SpringBoot使用swagger

• 导入依赖
  

• 2版本
  

1. <dependency>
2. <groupId>io.springfox</groupId>
3. <artifactId>springfox-swagger2</artifactId>
4. <version>2.9.2</version>
5. </dependency>
7. <dependency>
8. <groupId>io.springfox</groupId>
9. <artifactId>springfox-swagger-ui</artifactId>
10. <version>2.9.2</version>
11. </dependency>

复制代码

• 3.0版本
  

1. <dependency>
2. <groupId>io.springfox</groupId>
3. <artifactId>springfox-boot-starter</artifactId>
4. <version>3.0.0</version>
5. </dependency>

复制代码

• 编写swagger配置文件
  

1. @Configuration
2. @EnableSwagger2  //开启Swagger2
3. public class Swagger2Config {
4.     /**
5.      * 创建API应用
6.      * apiInfo() 增加API相关信息
7.      * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
8.      * 指定扫描的包路径来定义指定要建立API的目录。
9.      * @return
10.      */
11.     @Bean
12.     public Docket docket(){
13.         return new Docket(DocumentationType.SWAGGER_2)
14.                 .apiInfo(adminApiInfo())
15.                  //.enable(false) //enable是否启动Swagger 如果为false，则swagger不能在浏览器中访问
16.                 .groupName("adminApi")
17.                 .select()
18.                 //RequestHandlerSelectors 配置要扫描接口的方式
19.                 //basePackage: 指定要扫描的包
20.                 //any()：扫描全部
21.                 //none()不扫描
22.                 //withClassAnnotation: 扫描类上的注解，参数为一个注解的反射对象
23.                 //withMethodeAnnotation: 扫描方法上的注解
24.                 .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
25.                 //只显示admin下面的路径
26.                 .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
27.                 .build();
28.     }
30.     private ApiInfo adminApiInfo(){
31.         return new ApiInfoBuilder()
32.                 .title("api文档")
33.                 .description("系统接口描述")
34.                 .version("1.0")
35.                 //作者信息
36.                 .contact(new Contact("张三","http://baidu.com","12345678@qq.com"))
37.                 .build();
38.     }
39. }

复制代码

• 编写接口请求并运行
  

访问：http://localhost:8080/swagger-ui.html

使用：

• 实体类：
  
  
  
  • 1. @ApiModel("用户实体类")
    2. public class User{
    4.     @ApiModelProperty("用户名")
    5.     public String username;
    6. }

    复制代码
  
  
• 接口方法，参数：
  
  
  
  • 1. @RestController
    2. public class UserController{
    3.    
    4.     @ApiOperation("User控制类")
    5.     @GetMapping(value="/user")
    6.     public String getUser(@ApiParam("用户名")String username){
    7.     return "名字为："+username;
    8. }
    9. }

    复制代码
  
  

常用注解：

1. @Api：修饰整个类，描述Controller的作用,放在类上
3. @ApiOperation：描述一个类的一个方法，或者说一个接口
5. @ApiParam：单个参数描述
7. @ApiModel：用对象来接收参数
9. @ApiProperty：用对象接收参数时，描述对象的一个字段
11. @ApiResponse：HTTP响应其中1个描述
13. @ApiResponses：HTTP响应整体描述
15. @ApiIgnore：使用该注解忽略这个API
17. @ApiError ：发生错误返回的信息
19. @ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表
21. @ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
22. //eg:
23.     @ApiImplicitParam(name="username",value="用户名",required=true)

复制代码

Knife4j --Swagger增强工具

使用Knife4j2.06以上版本，springboot版本必须大于等于2.2.x

作用

• 可以搜索接口名称快速定位接口(搜索功能)
  
• 可以下载markdown、HTML、word 等格式文件(下载功能)
  

• 引入依赖
  

1. <dependency>
2.     <groupId>com.github.xiaoymin</groupId>
3.     <artifactId>knife4j-spring-boot-starter</artifactId>
4.     <version>2.0.9</version>
5. </dependency>

复制代码

• 添加SwaggerConfiguration作为Swagger2的配置类
  

1. @Configuration
2. @EnableSwagger2
3. @EnableKnife4j
4. //@EnableSwagger2WebMvc 2.6以上报空指针异常则需要添加
5. @Import(BeanValidatorPluginsConfiguration.class)
6. public class SwaggerConfiguration {
7.     @Bean
8.     public Docket api() {
9.         return new Docket(DocumentationType.SWAGGER_2)      // 选择swagger2版本
10.                 .apiInfo(apiInfo())         //定义api文档汇总信息
11.                 .select()
12.                 .apis(RequestHandlerSelectors
13.                         .basePackage("com.example"))  // 指定生成api文档的包
14.                 .paths(PathSelectors.any())     // 指定所有路径
15.                 .build();
16.     }
18.     /**
19.      * 构建文档api信息
20.      *
21.      * @return
22.      */
23.     private ApiInfo apiInfo() {
24.         return new ApiInfoBuilder()
25.                 .title("")     // 文档标题
26.                 .contact(new Contact("", "", ""))   //联系人信息
27.                 .description("")      //描述
28.                 .version("1.0.1")     //文档版本号
29.                 .termsOfServiceUrl("")     //网站地址
30.                 .build();
31.     }
32. }

复制代码

• 实现生产环境关闭文档资源
  

1. spring:
2.   profiles: prod #指定环境
3. knife4j:
4.    production: true #开启屏蔽文档资源

复制代码

• 实现接口排序
  

• 针对不同Controller排序：Controller上标注@ApiSupport(order = 序号)
  
• 针对同一个Controller中的不同方法排序：同一个Controller不同接口方法上标注@ApiOperationSupport(order = 序号)
  

注：更多详细配置可查看CSDN博主：swagger文档增强工具knife4j使用详解_baobao555#的博客-CSDN博客_knife4j swagger

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！