Swagger2搭建并使用

简介： 

     Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 Restfull 风格的 Web 接口服务，在当前前后端分离的情况下，利用swagger搭建一个接口服务平台，接口服务平台可以减少一些前后台的不必要沟通，前端只需要根据接口便可以进行前端开发。

1、添加swagger依赖

在需要生成文档的工程pom.xml文件中添加依赖

<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.9.2</version>
</dependency>
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.9.2</version>
</dependency>

2、编写配置类SwaggerConfig

@Configuration
@EnableSwagger2//声明这是swagger2文档类
public class SwaggerConfig implements WebMvcConfigurer {

    @Bean
    public Docket productApi(){
        //添加Head参数
        ParameterBuilder tokenPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<>();
        //封装令牌
        tokenPar.name("token").description("令牌").    //将token 转成中文
                modelRef(new ModelRef("string")). //
                parameterType("header").   //放在头里
                required(false).build();
        pars.add(tokenPar.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .select()//哪些包需要扫描生成文档
                .apis(RequestHandlerSelectors.basePackage("cn.wolfcode.wolf2w.controller"))//设定扫描路径，需要生成接口的包路径
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)//将上面配置好的token加载进去
                .apiInfo(metaData()); // 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    }

    /*    
    API具体信息内容
    */
    private ApiInfo metaData() {
        return new ApiInfoBuilder()
                .title("狼行天下项目-SpringBoot集成Swagger2")     // 页面标题
                .description("叩丁狼第四阶段项目文档")// 描述
                .version("V1.0.0")
                .contact(new Contact("温先生","","wenxiansheng@163.com"))// 创建人信息
                .license("Apache License Version 2.0")
                .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0")
                .build();
    }

    //UI界面展示
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")//访问的路径
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

注意：如果访问swagger-ui.html时出现“404” 可去检查是否拦截器拦截 如果拦截应该放行资源

拦截器放行：

//拦截器的注册-------------------------------------
    @Bean
    public CheckLoginInterceptor checkLoginInterceptor(){
        return new CheckLoginInterceptor();
    }
    //配置拦截的规则
​    @Override
​    public void addInterceptors(InterceptorRegistry registry) {
​        registry.addInterceptor(checkLoginInterceptor())
​                .addPathPatterns("/**")
​                .excludePathPatterns("/swagger-ui.html");//哪些拦截
​                //哪些放行
//                .excludePathPatterns("/users/checkPhone")
//                .excludePathPatterns("/users/sendVerifyCode")
//                .excludePathPatterns("/users/login")
//                .excludePathPatterns("/users/regist");
​    }  

生成文档的常用注解：

@Api：用在请求的类上，表示对类的说明
 tags="说明该类的作用，可以在UI界面上看到的注解"
 value="该参数没什么意义，在UI界面上也看到，所以不需要配置"

@ApiOperation：用在请求的方法上，说明方法的用途、作用
    value="说明方法的用途、作用"
    notes="方法的备注说明"

@ApiImplicitParams：用在请求的方法上，表示一组参数说明
    @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
        name：参数名
        value：参数的汉字说明、解释
        required：参数是否必须传
        paramType：参数放在哪个地方
            · header --> 请求参数的获取：@RequestHeader
            · query --> 请求参数的获取：@RequestParam
            · path（用于restful接口）--> 请求参数的获取：@PathVariable
            · body（不常用）
            · form（不常用）
        dataType：参数类型，默认String，其它值dataType="Integer"
        defaultValue：参数的默认值

@ApiResponses：用在请求的方法上，表示一组响应
    @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

@ApiModel：用于响应类上，表示一个返回响应数据的信息
            （这种一般用在post创建的时候，使用@RequestBody这样的场景，
            请求参数无法使用@ApiImplicitParam注解进行描述的时候）
    @ApiModelProperty：用在属性上，描述响应类的属性

@ApiIgnore：可以用在类、方法上，方法参数中，用来屏蔽某些接口或参数，使其不在页面上显示。

@ApiError：发生错误时返回的信息

@ApiParamImplicit：一个请求参数

@ApiParamsImplict：多个请求参数

代码改写：

/*
控制器
 */
@RestController
@RequestMapping("/users")
@Api(value = "用户资源",description = "用户资源控制器")  // value：说明     description：简介
public class UserController {
     @Autowired
    private IUserInfoService userInfoServer;
  
  //注册
    @PostMapping("/regist")
    @ApiOperation(value = "注册功能",notes = "新增一个用户")  // value :说明   不写显示方法名
    @ApiImplicitParams({
            @ApiImplicitParam(value = "手机号码",name = "phone",dataType = "String",required = true), //value :说明 name：字段 dataTyoe:参数类型，required：是否必须  （false：测试时候可以不填写）
            @ApiImplicitParam(value = "昵称",name = "nickname",dataType = "String",required = true),
            @ApiImplicitParam(value = "密码",name = "password",dataType = "String",required = true),
            @ApiImplicitParam(value = "确认密码",name = "rpassword",dataType = "String",required = true),
            @ApiImplicitParam(value = "短信验证码",name = "verifyCode",dataType = "String",required = true),
    })
    public Object regist( String phone, String nickname, String password, String rpassword, String verifyCode) {
      
        userInfoServer.regist(phone,nickname,password,rpassword,verifyCode);
        return JsonResult.success();
    }
    @GetMapping("/person")
    @ApiResponses({//响应
            @ApiResponse(code = 200,message = "查询用户信息成功")
    })
    public Object person(Person person){
        return JsonResult.success(person);
    }

}

 实体类的使用：

@Getter
@Setter
@ApiModel(value = "人实体类", description = "用于API接口测试实体模型")   //value 备注   description 描述
public class Person {

    @ApiModelProperty(value = "用户id", name = "id", dataType = "String", required = true)
    private String id;
    @ApiModelProperty(value = "用户姓名", name = "name", dataType = "String", required = true)
    private String name;
    @ApiModelProperty(value = "用户年龄", name = "age", dataType = "String", required = true)
    private String age;
}

测试

启动工程，在浏览器输入 http://localhost:8080/swagger-ui.html#/ 可以看到