Swagger2 详解-白红宇

Swagger2 详解

阅读量：3960 次

发布时间：2019-05-24

本文共 2982 字，大约阅读时间需要 9 分钟。

1、Swagger2简介

当下很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成。在这种开发模式下，维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的，相信大家也都知道这种方式很难保证文档的及时性，这种文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式。

2、依赖引入


      
    
     io.springfox
       
    
     springfox-swagger2
       
    
     2.9.2
    
   
      
    
     io.springfox
       
    
     springfox-swagger-ui
       
    
     2.9.2

3、启动类配置

在使用 Springboot 项目时，我们还需要在启动类添加 @EnableSwagger2 注解。

这个时候我们添加一个controller并写入方法，直接启动项目打开swagger-ui

4、添加Swagger配置类

我们添加一个用于配置SwaggerUI的配置类。

@Bean    public Docket docket(){
           Docket docket = new Docket(DocumentationType.SWAGGER_2);        ApiInfo apiInfo = new ApiInfoBuilder().contact(new Contact("lzq","http://www.baidu.com","2645922971@qq.com"))                .title("Lzq-Api")                .description("Lzq-Api-Swagger-description")                .version("1.0")                .build();        docket.apiInfo(apiInfo);        return docket;    }

在这里插入图片描述

还可添加指定扫描的包

// 扫描指定包        docket                .select()                // 方法上有注解@AnnoSwagger的时候返回true 最后取反                .apis(Predicates.not(RequestHandlerSelectors.withMethodAnnotation(AnnoSwagger.class)))                // 限制生成API文档的路径地址                // 还可以使用 Predicates 的 and or 方法进行或且 运算                .paths(PathSelectors.regex("/swagger/.*"))                // 调用build重新构建                .build();                // 只能调一次 不可覆盖                // .apis(RequestHandlerSelectors.basePackage("com.lzq.controller"));

并且这里的AnnoSwagger是一个自定义注解，用来限制Swagger文档不进行显示对应的方法

import java.lang.annotation.ElementType;import java.lang.annotation.Retention;import java.lang.annotation.RetentionPolicy;import java.lang.annotation.Target;@Retention(RetentionPolicy.RUNTIME)@Target(ElementType.METHOD)public @interface AnnoSwagger {
   }

5、相关注解详解

5.1、@Api

tags 给当前类型定义别名可以有多个，description 当前类型生成的帮助文档的描述信息

@Api(tags = {
   "hellloController", "SwaggerDemoController"}, description = "swagger-Api-controller")

5.2、@ApiOperation

用来描述方法

@ApiOperation(value = "hello", notes = "hello method get request")

5.3、@ApiParam

作用于入参，用来描述参数

@ApiParam(name = "用户名", value = "value - 用户名", required = true) String name

5.4、@ApiImplicitParam

作用于方法，用来描述参数

@ApiImplicitParam(name = "name", value = "name - value", required = true, paramType = "String")

5.5、@ApiImplicitParams

作用于方法，用来描述多个参数

@ApiImplicitParams(value = {
               @ApiImplicitParam(name = "name", value = "name - value", required = true, paramType = "String"),            @ApiImplicitParam(name = "PassWord", value = "PassWord - value", required = true, paramType = "String")    })

5.6、@ApiIgnore

作用于方法，用来忽略生成该方法的Api文档

5.7、@ApiModel

作用于实体类，当成为帮助文档上的接口返回值类型时，即被解析

@ApiModel(value = "自定义实体类", description = "User Object")

5.8、@ApiModelProperty

作用于实体类对应的属性，进行描述

@ApiModelProperty(value = "姓名 - value", name = "姓名 - name", required = false, example = "月月鸟", hidden = false)    private String name;

6、Swagger-UI的使用

对于返回实体类可以在Models当中查看，其余方法（请求接口）在对应的controller类当中进行查看。

在这里插入图片描述

转载地址：http://gkqzi.baihongyu.com/

你可能感兴趣的文章