温馨提示×

温馨提示×

您好,登录后才能下订单哦!

密码登录×
登录注册×
其他方式登录
点击 登录注册 即表示同意《亿速云用户服务条款》

Swagger及knife4j怎么使用

发布时间:2022-08-23 11:26:39 来源:亿速云 阅读:252 作者:iii 栏目:开发技术

这篇文章主要介绍了Swagger及knife4j怎么使用的相关知识,内容详细易懂,操作简单快捷,具有一定借鉴价值,相信大家阅读完这篇Swagger及knife4j怎么使用文章都会有所收获,下面我们一起来看看吧。

    Swagger 介绍:

    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

    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

    作用

    • 可以搜索接口名称快速定位接口(搜索功能)

    • 可以下载markdown、HTML、word 等格式文件(下载功能)

    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.实现接口排序

    • 针对不同Controller排序:Controller上标注@ApiSupport(order = 序号)

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

    关于“Swagger及knife4j怎么使用”这篇文章的内容就介绍到这里,感谢各位的阅读!相信大家对“Swagger及knife4j怎么使用”知识都有一定的了解,大家如果还想学习更多知识,欢迎关注亿速云行业资讯频道。

    向AI问一下细节

    免责声明:本站发布的内容(图片、视频和文字)以原创、转载和分享为主,文章观点不代表本网站立场,如果涉及侵权请联系站长邮箱:is@yisu.com进行举报,并提供相关证据,一经查实,将立刻删除涉嫌侵权内容。

    AI