在项目中使用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/", "XXXxxXX@qq.com"))
                //版本号
                .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

4.如何在项目访问当前生成这个swagger文档？ 

我此时项目的端口是8084 所以在页面上访问路径为：http://localhost:8084/swagger-ui.html