亲宝软件园·资讯

展开

Swagger knife4j使用

ProsperousEnding 人气:0

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接口访问,不会使服务端资源状态发生改变

优点:

SpringBoot使用swagger

  1. 导入依赖
  2. 2版本
<!--swagger依赖-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger ui-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>

3.0版本

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>

2.编写swagger配置文件

@Configuration
@EnableSwagger2  //开启Swagger2
public class Swagger2Config {
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
     * 指定扫描的包路径来定义指定要建立API的目录。
     * @return
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(adminApiInfo())
                 //.enable(false) //enable是否启动Swagger 如果为false,则swagger不能在浏览器中访问
                .groupName("adminApi")
                .select()
                //RequestHandlerSelectors 配置要扫描接口的方式
                //basePackage: 指定要扫描的包
                //any():扫描全部
                //none()不扫描
                //withClassAnnotation: 扫描类上的注解,参数为一个注解的反射对象
                //withMethodeAnnotation: 扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                //只显示admin下面的路径
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();
    }

    private ApiInfo adminApiInfo(){
        return new ApiInfoBuilder()
                .title("api文档")
                .description("系统接口描述")
                .version("1.0")
                //作者信息
                .contact(new Contact("张三","http://baidu.com","12345678@qq.com"))
                .build();
    }
}

3.编写接口请求并运行

访问方式(本地):http://localhost:8080/swagger-ui.html

使用:

实体类:

@ApiModel("用户实体类")
public class User{

    @ApiModelProperty("用户名")
    public String username;
}

接口方法,参数:

@RestController
public class UserController{
    
    @ApiOperation("User控制类")
    @GetMapping(value="/user")
    public String getUser(@ApiParam("用户名")String username){
    return "名字为:"+username;
} 
}

常用注解:

@Api:修饰整个类,描述Controller的作用,放在类上

@ApiOperation:描述一个类的一个方法,或者说一个接口

@ApiParam:单个参数描述

@ApiModel:用对象来接收参数

@ApiProperty:用对象接收参数时,描述对象的一个字段

@ApiResponses:HTTP响应整体描述

@ApiResponse:HTTP响应其中1个描述

@ApiIgnore:使用该注解忽略这个API

@ApiError :发生错误返回的信息

@ApiImplicitParams:描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

@ApiImplicitParam:描述一个请求参数,可以配置参数的中文含义,还可以给参数设置默认值
//eg:
    @ApiImplicitParam(name="username",value="用户名",required=true)

Knife4j --Swagger增强工具

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

作用

1.引入依赖

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

2.添加SwaggerConfiguration作为Swagger2的配置类

@Configuration
@EnableSwagger2
@EnableKnife4j
//@EnableSwagger2WebMvc 2.6以上报空指针异常则需要添加
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)      // 选择swagger2版本
                .apiInfo(apiInfo())         //定义api文档汇总信息
                .select()
                .apis(RequestHandlerSelectors
                        .basePackage("com.example"))  // 指定生成api文档的包
                .paths(PathSelectors.any())     // 指定所有路径
                .build();
    }

    /**
     * 构建文档api信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("")     // 文档标题
                .contact(new Contact("", "", ""))   //联系人信息
                .description("")      //描述
                .version("1.0.1")     //文档版本号
                .termsOfServiceUrl("")     //网站地址
                .build();
    }
}

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

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

4.实现接口排序

注:更多详细配置:swagger文档增强工具knife4j使用详解

加载全部内容

相关教程
猜你喜欢
用户评论