Swagger3实现API文档管理：让前后端合作更加顺畅

Swagger介绍

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

Swagger3配置

1、添加相应依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2、编写一个配置类来启动Swagger

@Configuration
/**
 * 解决springboot版本太高问题
 */
@EnableWebMvc
@EnableOpenApi
public class SwaggerConfig {

}

3、启动即可

4、可以在配置类里面添加一些自己的信息,也可以添加多个用户

    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("李小红");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("李白");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("火舞");
    }

    @Bean
   public Docket docket(Environment environment){
        Profiles profiles = Profiles.of("dev", "test");
        // 判断是否处于自己设置的环境中
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                // 根据环境是否开启swagger
                .enable(flag)
                .groupName("齐菁菁")
                .select()
                //RequestHandlerSelectors配置要扫描接口的方式
                //basePackage() 扫描指定路径下的包
                //any() 扫描所有
                //none() 都不扫描
                //withClassAnnotation()扫描指定的注解
                // GetMapping()扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.lili.controller"))
//                过滤掉一些路径扫描
//                .paths(PathSelectors.ant("/lili/**"))
                .build();
    }

    /**
     * 配置swagger信息apiInfo，作者信息
     */
    public ApiInfo apiInfo(){
        Contact contact = new Contact("齐菁菁", "https://www.baidu.com/", "qijingjing01@126.com");
        return new ApiInfo("齐菁菁的swaggerApi文档",
                "你尽管努力,剩下的交给天意",
                "1.0",
                "www.baidu.com",
                contact,
                "Apache 2.0",
                "http://localhost:8080/tmall/admin",
                new ArrayList());
    }

5、设置swagger的应用环境

• 我们一般在测试或者开发阶段允许swagger生效

• 在yml里面进行配置环境

• 上面的配置内容会读取环境，按需开启swagger

spring.profiles.active=test

6、相关信息配置完成后，我们的页面就变成了

具体使用

1、新建一个实体类

@Data
@ApiModel("用户实体类")
public class Person {
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty("年龄")
    private int age;
}

2、编写控制层

@RestController
public class PersonController {
    @GetMapping("/person")
    @ApiOperation("测试类1，返回person字符串")
    public String test1(){
        return "person";
    }
    @GetMapping("/person2")
    @ApiOperation("测试类2，返回一个person对象")
    public Person getPerson(){
        return new Person();
    }
    @GetMapping("/person3")
    @ApiOperation("输入用户名和年龄，然后进行返回")
    public String getUsernameAndAge(@ApiParam("用户名") String username, @ApiParam("年龄") int age){
        return "用户名是"+username+",年龄为"+age;
    }
}

3、运行显示