J-框架-springboot-Swagger

Swagger

Restful Api 文档在线自动生成器 => API 文档 与API 定义同步更新。直接运行，在线测试API。
使用
springboot集成Swagger

1.导入依赖

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

2.集成Swagger

package com.spring_01.config;

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
   
}

运行：
http://localhost:8080/swagger-ui.html

3.配置Swagger

package com.spring_01.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiListing;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration //配置类
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig {

    //配置文档信息
    private ApiInfo apiInfo(){
        Contact contact = new Contact("联系人名字", "http://xxx.xxx.com/联系人访问链接", "联系人邮箱");
        return new ApiInfo(
          "Swagger学习", //标题
          "配置Swagger",//描述
          "v1.0",//版本
          "http://baidu.com",//组织连接
          contact,//联系人信息
          "Apach 2.0许可",//许可
          "许可连接",//许可连接
          new ArrayList<>()
        );
    }

    //配置docket，配置具体Swagger参数
    //Docket实例关联上配置信息
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }

}

配置结果：

4.配置扫描接口

配置哪些接口可以被扫描哪些不能被扫描

//配置docket，配置具体Swagger参数
    //Docket实例关联上配置信息
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                .apis(RequestHandlerSelectors
                        //扫描方法
                        //.basePackage("com.kuang.swagger.controller")//扫描包
                        //any() // 扫描所有，项目中的所有接口都会被扫描到
                        //none() // 不扫描接口
                        //withMethodAnnotation(GetMapping.class)// 通过方法上的注解扫描，如只扫描get请求
                        //.withClassAnnotation(Controller.class)//通过类上的注解扫描，如只扫描有controller注解的类中的接口
                        //basePackage(final String basePackage) // 根据包路径扫描接口
                        .withMethodAnnotation(GetMapping.class))
                //配置如何通过path过滤,
                .paths(PathSelectors
                        //.ant("/kuang/**"))//只扫描请求以/kuang开头的接口
                        //any() // 任何请求都扫描
                        //none() // 任何请求都不扫描
                        //regex(final String pathRegex) // 通过正则表达式控制
                        .ant("/kuang/**"))
                .build();
    }

5.配置Swagger开关

1、通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了。

当开发完成后上线时，可以将swagger开关改为false。

6,.配置API分组

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

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

2.多个配置分组

  //分组配置
    @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");
    }

结果：

7.配置实体类

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用户实体")
public class Account {

    @ApiModelProperty("用户id")
    private int id;
    @ApiModelProperty("用户名")
    private String name;
    @ApiModelProperty("账户金额")
    private String money;
}

结果：

@RestController
public class AccountController {

    @Autowired
    AccountMapper accountMapper;

    //查询全部账户
    @ApiOperation("查询全部账户")
    @GetMapping("/queryAccountList")
    public List<Account> queryAccountList(){

        System.out.println("进入controller了-------------");

        List<Account> accountList = accountMapper.queryAccountList();
        System.out.println("打印结果"+accountList);

        return accountMapper.queryAccountList();
    }

    //查询账户
    @ApiOperation("查询账户")
    @PostMapping("/queryAccountById")
    public Account queryAccountById(){

        System.out.println("进入controller了-------------");
        return accountMapper.queryAccountById(3);
    }

    //添加账户
    @ApiOperation("添加账户")
    @GetMapping("/addAccount")
    public String addAccount(){

        Account account = new Account(10,"测试人员","100");
        System.out.println("进入controller了-------------");
        return "结果："+accountMapper.addAccount(account);
    }

}

结果：

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

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

Swagger注解 简单说明
①：@Api(tags = “xxx模块说明”) 作用在模块类上
②：@ApiOperation(“xxx接口说明”) 作用在接口方法上
③：@ApiModel(“xxxPOJO说明”) 作用在模型类上：如VO、BO
④：@ApiModelProperty(value = “xxx属性说明”,hidden = true) 作用在类方法和属性上，hidden设置为true可以隐藏该属性
⑤：@ApiParam(“xxx参数说明”) 作用在参数、方法和字段上，类似@ApiModelProperty