Springboot整合Swagger接口框架常用注解与自定义ui

写在前边： 前后端分离的大趋势，我们需要一个好的api文档工具，其中swagger是一个很不错的api框架。

新建springbootweb项目

导入swagger依赖：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

配置类：

@Configuration
@EnableSwagger2 //开启swagger
public class SwaggerConfig {
}

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

入门配置：

1.配置一个swaggerconfig类：

@Configuration//表明配置类
@EnableSwagger2//开启Swagger2的自动注解
public class SwaggerConfig {
}

2.配置docket以配置Swagger具体参数

/**
 *   配置docket以配置Swagger具体参数：一个docket一个分组
 */
@Bean
public Docket docket(){
    return new Docket(DocumentationType.SWAGGER_2)；
}

3.配置文档信息：

/**
 * 配置文档信息
 */
public ApiInfo apiInfo(){
    /*
           private final String name;
           private final String url;
           private final String email;
    */
    //联系人信息
    Contact contact = new Contact("Codewhite","http://codewhite.cn","405773808@qq.com");
    return new ApiInfo(
      "Swagger项目练习",// 标题
            "配置Swagger的文档",// 描述
            "v1.0", // 版本
            "http://codewhite.cn",// 组织链接
            contact, // 联系人信息
            "Apach 2.0 许可",// 许可
            "许可链接", // 许可连接
            new ArrayList<>()// 扩展

    );

4.将配置信息加入docket

   /**
     *   配置docket以配置Swagger具体参数
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

测试：http://localhost:8080/swagger-ui.html

配置扫描接口

@Configuration//配置类
@EnableSwagger2//启用swagger
public class SwaggerConfig {

    /**
     * 配置docket以配置Swagger具体参数
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                //通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
            
                /* apis可填的值 配置如何扫描接口
                any() // 扫描所有，项目中的所有接口都会被扫描到
                none() // 不扫描接口
                1.通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
                withMethodAnnotation(final Class<? extends Annotation> annotation)
                2.通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
                withClassAnnotation(final Class<? extends Annotation> annotation)
                basePackage(final String basePackage) // 根据包路径扫描接口
                 */
                .select().apis(RequestHandlerSelectors.basePackage("cn.codewihte.controller"))
                /*  paths 配置过滤
                 *  any() // 任何请求都扫描
                 *  none() // 任何请求都不扫描
                 *  regex(final String pathRegex) // 通过正则表达式控制
                 *  ant(final String antPattern) // 通过ant()控制
                 */
                .paths(PathSelectors.ant("/xiaobai/**")).build();


    }
}

配置Swagger开关

如何动态配置当项目处于test、dev环境时显示swagger，处于生产环境时不显示：

@Bean
    public Docket docket(Environment environment) {

        // 设置要显示swagger的环境
        Profiles profiles = Profiles.of("dev","test");

        // 判断当前是否处于该环境 如果处于显示true
        boolean isFlag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .enable(isFlag) //配置是否启用Swagger，如果是false，在浏览器将无法访问
                .select().apis(RequestHandlerSelectors.basePackage("cn.codewihte.controller"))
                .build();

    }

配置API分组

1、如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组：hello分组
       
}

3、配置多个分组只需要配置多个docket即可：

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

常用注解

tars:相当于配了一个组

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty
@ApiIgnore()用于类，方法，方法参数	表示这个方法或者类被忽略
@ApiImplicitParams、@ApiImplicitParam	方法的参数的说明；@ApiImplicitParams 用于指定单个参数的说明
@ApiResponses、@ApiResponse	方法返回值的说明 ；@ApiResponses 用于指定单个参数的说明…
…	…

其中：@ApiOperation()

@ApiOperation()写在方法里	用处
value	用于方法描述
notes	用于提示内容
tags	可以重新分组（视情况而用）

@ApiParam() 用于方法，参数，字段说明

@ApiParam()	用处
name	参数名
value	参数说明
required	是否必填

@Api(value="用户控制器",tags={"用户操作接口"})
@RestController
@RequestMapping("/user")
public class UserController {


    @ApiOperation(value="获取所有用户",tags={"获取用户信息copy"},notes="注意问题点")
    @GetMapping("/getAll")
    public User user(@ApiParam(name="name",value="用户名") String name){
        return new User();
    }

我们也可以给请求的接口配置一些注释

    @ApiOperation("响应hello")
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

@ApiModel()用于实体类

ApiModel()	作用
value	表示对象名
description	描述

@ApiModelProperty()用于方法，字段

@ApiModelProperty()	作用
value	字段说明
name	重写属性名字
dataType	重写属性类型
required	是否必填
example	举例说明
hidden	hidden–

实体配置：

1、新建一个实体类

@ApiModel(value="user",description="用户对象user")
public class User {

    @ApiModelProperty(value="用户名",name="username",example="admin")
    public String username;
    @ApiModelProperty(value="密码",name="password",required=true)
    public String password;

}

2、将实体类请求接口的返回值上，能映射到实体项中：

   @ApiOperation(value="获取所有用户",tags={"获取用户信息copy"},notes="注意问题点")
    @GetMapping("/getAll")
    public User user(@ApiParam(name="name",value="用户名") String name){
        return new User();
    }

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。swagger-ui 自定义

@ApiImplicitParam 单个参数

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

@ApiImplicitParams()	用处
name	参数名称
value	参数说明
dataType	数据类型
paramTyp	参数类型
example	举例说明

@ApiImplicitParams({
        @ApiImplicitParam(name = "username", value = "用户名", dataType = "string", paramType = "update", example = "admin"),
        @ApiImplicitParam(name = "id", value = "用户id", dataType = "long", paramType = "update"),
        @ApiImplicitParam(name = "email", value = "邮箱", dataType = "string", paramType = "update")
})
@PutMapping("/user")
public String update(String username, Integer id, String email) {

    return "success";
}

@ApiResponses、@ApiResponse方法返回对象的说明

@ApiResponse	方法返回对象的说明
code	相应码
message	响应信息
response	抛出的异常类.class

SwaggerUi定制：

1、默认的 访问 http://localhost:8080/swagger-ui.html

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

效果：

2、bootstrap-uihttp://localhost:8080/doc.html

<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>

效果：

3、Layui-ui 访问 http://localhost:8080/docs.html

<!-- 引入swagger-ui-layer包 /docs.html-->
<dependency>
   <groupId>com.github.caspar-chen</groupId>
   <artifactId>swagger-ui-layer</artifactId>
   <version>1.1.3</version>
</dependency>

效果：

4、mg-ui 访问 http://localhost:8080/document.html

<!-- 引入swagger-ui-layer包 /document.html-->
<dependency>
   <groupId>com.zyplayer</groupId>
   <artifactId>swagger-mg-ui</artifactId>
   <version>1.0.6</version>
</dependency>

效果：

写在后边：

以上学习资料来自：swagger官网，b站狂神等。如有问题可以私信我