在项目中使用Swagger文档

1.为什么要使用Swagger？

前后端协作开发过程中，时间周期一长，接口文档就变得难以维护，而我们通过swagger 只需要平常在写代码的时候加上一些注解，就可以生成一个接口在线文档，进行一些简单的功能测试！

2.如何使用Swagger?

1）.需要在pom.xml中引用jar包

复制出来：

<!-- swagger start -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.7.0</version>
</dependency>
<!-- swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>
<!-- swagger end -->

2）.配置swagger文档的配置类

package com.test;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * 功能描述: swagger文档的配置类
 * @Author: tanghh18
 * @Date: 2019/9/27 13:51
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {
    /**
     * swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage
                        ("com.test.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("前端 API")
                //创建人
                .contact(new Contact("soup_tang", "http://localhost:8084/", "[email protected]"))
                //版本号
                .version("1.0")
                //描述
                .description("加油！")
                .build();
    }
}

3. Swagger常用的注解

@Api() 主要是用来描述当前类的作用，description是在swagger文档页面展示的备注信息

@ApiOperation() value这个参数不在文档上面展示，notes是在文档上面展示的内容，httpMethod 是get 还是post请求

@ApiModelProperty 主要是用来描述当前这个参数的作用

还有一些其他的注解：

（1）@ApiImplicitParams : 用在方法上包含多个参数说明。

（2）@ApiImplicitParam：用在方法上包含一个参数说明。

paramType：指定参数放在哪个地方。
name：参数名
dataType：参数类型
required：参数是否必须传
value：说明参数
defaultValue：参数的默认值

header：请求参数放置于Request Header，使用@RequestHeader 获取。
query：请求参数放置于请求地址，使用@RequestParam获取
path：用于restful接口。
（3）@ApiResponses：用于表示一组响应。

（4）@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息。

code：数字，例如400。
message：信息，例如"请求参数没填好"。
response：抛出异常的类。
————————————————
版权声明：本文为CSDN博主「XuDanT」的原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接及本声明。
原文链接：https://blog.csdn.net/xudant/article/details/82856555