简介

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无需访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger 的优势

• 支持 API 自动生成同步的在线文档：使用 Swagger 后者可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

1.快速开始

1）创建一个SpringBoot工程，配置相关依赖

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

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.20</version>
        <scope>provided</scope>
    </dependency>

2）配置swagger的Docker的Bean实例

/**
 * @author zyp
 * @create 2021/10/13
 */
@Configuration
@EnableSwagger2 //开启swagger2
public class SwaggerConfig {

    /**
     * 配置swagger的Docker的Bean实例（可配置多个，因为有组的概念）
     * @return
     */
    @Bean
    public Docket docket(Environment environment){
        //查看当前环境是否是dev环境，如果是dev环境将开启swagger，其它环境关闭swagger
        Profiles profile = Profiles.of("dev");
        boolean flag = environment.acceptsProfiles(profile);

        return new Docket(DocumentationType.SWAGGER_2)
                //是否开启swagger
                .enable(flag)
                //分组
                .groupName("swagger文档A")
                .apiInfo(new ApiInfo(
                "Api Documentation",
                "Api Documentation",
                "1.0",
                "urn:tos",
                 new Contact("", "", ""),
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                 new ArrayList()))
                .select()
                /**
                 *  配置swagger扫描包
                 *  any:全部扫描
                 *  none:不扫描
                 *  basePackage:扫描指定包
                 *  withClassAnnotation:扫描类上带有指定的注解
                 *  withMethodAnnotation:扫描方法上指定的注解
                 */
                .apis(RequestHandlerSelectors.basePackage("com.zyp.swagger"))
                //过滤不需要扫描的包
//                .paths(PathSelectors.any())
                .build();

    }

    @Bean
    public Docket docket1(Environment environment){
        //查看当前环境是否是dev环境，如果是dev环境将开启swagger，其它环境关闭swagger
        Profiles profile = Profiles.of("dev");
        boolean flag = environment.acceptsProfiles(profile);

        return new Docket(DocumentationType.SWAGGER_2)
                //是否开启swagger
                .enable(flag)
                //分组
                .groupName("swagger文档B")
                .apiInfo(new ApiInfo(
                        "Api Documentation",
                        "Api Documentation",
                        "1.0",
                        "urn:tos",
                        new Contact("", "", ""),
                        "Apache 2.0",
                        "http://www.apache.org/licenses/LICENSE-2.0",
                        new ArrayList()))
                .select()
                .build();

    }
}

3）编写实体类与Controller案例

/**
 * @author zyp
 * @create 2021/10/13
 */
@Api(tags="案例展示Controller")
@Slf4j
@RestController
public class HelloController {
    /**
     * 无参请求案例
     * @return
     */
    @ApiOperation(value="helloword案例",notes="无参请求案例")
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    /**
     * 请求、响应参数为对象案例
     * @param user
     * @return
     */
    @ApiOperation(value="获取用户信息接口",notes="请求、响应参数为对象案例")
    @PostMapping("/getUserInfo")
    public User getUserInfo(@RequestBody User user){
        return user;
    }

    /**
     * 请求参数类型不是对象的案例
     * @param username
     */
    @ApiOperation(value="查询用户信息",notes="请求、请求参数类型不是对象的案例")
    @ApiImplicitParams({
            @ApiImplicitParam(name="username",value="用户名称",required=true,dataType="String")
    })
    @PostMapping("/queryUserInfo")
    public void queryUserInfo(String username){
        log.info("########################"+username);
    }
}

/**
 * @author zyp
 * @create 2021/10/14
 */
@Data
@ApiModel(description = "用户信息")
public class User {
    @ApiModelProperty(value = "用户名",required=true)
    private String username;
    @ApiModelProperty(value = "密码",required=true)
    private String password;
}

4）启动spring boot工程访问swagger-ui界面（访问地址：http://localhost:8080/swagger-ui.html）

2.swagger-ui界面介绍

1）第一部分：swagger相关介绍对应的docker配置

2）第二部分：接口相关文档

对应的代码

3）第三部分：实体类相关介绍

4）第四部分：文档分类

3.swagger注解介绍

1）用于controller类上：

@Api：请求类的说明

@Api：放在 请求的类上，与 @Controller 并列
	tags="说明该类的作用"
	value="该参数没什么意义，所以不需要配置"

案例

2）用于方法上面（说明参数的含义）：

@ApiOperation：方法的说明

@ApiOperation："用在请求的方法上，说明方法的作用"

value="说明方法的作用"

notes="方法的备注说明"

案例

@ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明

@ApiImplicitParam：对单个参数的说明

name：参数名

value：参数的说明、描述

required：参数是否必须必填

paramType：参数放在哪个地方

· query --> 请求参数的获取：@RequestParam

· header --> 请求参数的获取：@RequestHeader

· path（用于restful接口）--> 请求参数的获取：@PathVariable

· body（请求体）--> @RequestBody User user

· form（普通表单提交）

dataType：参数类型，默认String，其它值dataType="Integer"

defaultValue：参数的默认值

案例

3）@ApiModel：用于JavaBean上面，表示对JavaBean 的功能描述 @ApiModelProperty：用在JavaBean类的属性上面，说明属性的含义

案例

4）注意事项

controller中一定不要写@RequestMapper，否则swagger-ui界面中的接口文档可能出现多个，我们可以指定请求方式，如：@GetMapper、@PostMapper

4.swagger模拟请求功能介绍

点击“执行”接口返回数据展示

对源码感兴趣的朋友可以到码云下载：https://gitee.com/zhengyiping/swagger.git