Swagger前后端开发自动生成API 文件，牛逼不

一、Swagger简介

现在我们常用的前后端分离框架 Vue + springboot 技术。
Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲，Swagger 就是将项目中所有（想要暴露的）接口展现在页面上，并且可以进行接口调用和测试的服务。
swagger 号称世界上最牛逼的 Api框架。
可以直接在线测试 后端 Api 接口
官网：https://swagger.io/

二、Swagger 2.9.2 的使用分为以下 4 步：

1. 添加依赖 ： 去 maven仓库（https://mvnrepository.com/）中，搜索springfox，复制springfox-swagger2，springfox-swagger-ui 两个依赖。添加到 pom文件中（在3.0以上版本，只需添加springfox这个总依赖即可）

注意：springboot 的版本 出现不兼容 Swagger版本问题，如果采用 2.6版本springboot，就会报错。

 <!--使用swagger必须导入依赖，不然报红-->
        <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>

springboot版本：

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.7.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>

2. 开启 Swagger ：（在3.0以上版本中，开启用@EnableOpenApi）

**在 Spring Boot 的启动类或配置类中添加 @EnableSwagger2 注释，开启 Swagger，部分核心代码如下：** @Configuration @EnableSwagger2 // 开启swagger

html访问页面：http://localhost:8081/swagger-ui.html

（1）swagger的首页页面的相关信息 修改为与自己项目相关

（2）配置swagger 扫描的包

.select()
//RequestHandlerSelectors.basePackage(“com.swagger.swagger.controller”) 指定扫描的包
//RequestHandlerSelectors.any 表示全部扫描，一般都是指定扫描包
//RequestHandlerSelectors.none 表示都不扫描
.apis(RequestHandlerSelectors.basePackage(“com.swagger.swagger.controller”))
//路径过滤
//.paths(PathSelectors.ant("/swagger/**"))
.build();

package com.swagger.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.RequestHandlerProvider;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
/**
 * @Author Janson
 * @Date 2022/3/5 15:27
 * @Version 1.0
 */
@Configuration
@EnableSwagger2 // 开启swagger ,也可以把该注解放在 SwaggerApplication 启动类上方
//如果放在此处出现无法访问，可以尝试放在启动类上方
public class SwaggerConfig {
    //docket1 和 docket 两个类的对象，主要 是对api进行分组，各个分组负责自己的api
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("小葵花");
    }
    @Bean
    public Docket docket(Environment environment){
        //获取 环境变量
        //设置要显示的swagger 环境
        Profiles profiles = Profiles.of("dev");
        boolean flag = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否启动swagger
                .enable(flag)
                .groupName("大太阳")
                .select()
                //RequestHandlerSelectors.basePackage("com.swagger.swagger.controller") 指定扫描的包
                //RequestHandlerSelectors.any 表示全部扫描，一般都是指定扫描包
                //RequestHandlerSelectors.none 表示都不扫描
                .apis(RequestHandlerSelectors.basePackage("com.swagger.swagger.controller"))
                //路径过滤
                //.paths(PathSelectors.ant("/swagger/**"))
                .build();
    }
    private ApiInfo apiInfo(){
        Contact DEFAULT_CONTACT = new Contact("Janson", "http://www.baidu.com", "12242qq.com");
        return new ApiInfo("dongGod",
                "我要好好写代码",
                "1.0",
                "http://www.baidu.com",
                DEFAULT_CONTACT,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

3. 功能 配置 Swagger 扫描接口
我只希望我的swagger 在生产环境用，在发布的时候不使用。该如何解决?

• 判断是不是生产环境 flag
• 注入 enable(flag)

public class SwaggerConfig {
    @Bean
    public Docket docket(Environment environment){
        //获取 环境变量
        //设置要显示的swagger 环境
        Profiles profiles = Profiles.of("dev");
        boolean flag = environment.acceptsProfiles(profiles);
        }

Docket.select()

4.配置api分组,通过创建多个Docket类的对象，对api文档实现分组

groupname();

5.实体类： 只要我们的接口中，存在返回值实体类，他就会扫描到swagger 中

package com.swagger.swagger.controller;

import ch.qos.logback.classic.spi.STEUtil;
import com.swagger.swagger.entity.Student;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @Author Janson
 * @Date 2022/3/5 20:01
 * @Version 1.0
 */
//给接口加api注释
@RestController
public class Students {
    //只要我们的接口中，存在返回值实体类，他就会扫描到swagger 中
    //Operation给方法加注释
    @ApiOperation("控制了接口")
    @GetMapping("/student")
    public Student student(String name, String password){
        Student student = new Student();
        student.name = name;
        student.password = password;
        return student;
    }
}

package com.swagger.swagger.entity;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

/**
 * @Author Janson
 * @Date 2022/3/5 19:57
 * @Version 1.0
 */
//加中文注释
@ApiModel("学生实体类")
public class Student {
    @ApiModelProperty("用户名")
    public String name;
    @ApiModelProperty("密码")
    public String password;
}

启动成功访问前端：

html访问页面：http://localhost:8081/swagger-ui.html

6.总结：

1. 我们可以通过swagger 给一些比较难理解的属性或者接口，增加注释属性
2. 接口文档实时更新
3. 可以在线测试

【注意点】：在正式发布的时候，要关闭swagger，出于安全考虑，并提高程序执行效率