Swagger萌新上手

Swagger是什么

简单来说，就是一套后端Api开发规范，仅作用于Controller层。
（1）使用注解简化api接口的定义与说明，
（2）利用自带开源的可视化工具实现生成可视化接口文档，方便前后端联调，尽可能避免前后端工程师打架的情况。

如何使用

swagger是基于前后端分离项目的，这里以spring-boot项目配置swagger为例。

配置swagger

一、首先引入spring-boot swagger的maven依赖
其中 swagger UI主要是实现可视化接口文档并实现接口测试，相当于集成了postman的功能，前端只需访问指定url，就可以查看swagger自己生成的接口文档。

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

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>

二、编写swagge配置文件
创建SwaggerConfig.java文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.Controller"))//扫描指定包下所有接口
                //设置扫描的方式
               // .apis(RequestHandlerSelectors.none())//不扫描接口
               // .apis(RequestHandlerSelectors.any())//扫描所有接口
               // .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))//扫描所有带有@GetMapping注解的方法的接口
               // .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))//扫描所有带有@RestController注解的类下的接口
                //设置指定的请求映射路径路径，可以与上同时使用
                .paths(PathSelectors.ant("/bye/**"))
                .build();
//        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
    }


    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Spring Boot 使用 Swagger2 构建RESTful API")
                //创建人
                .contact(new Contact("周立波", "http://www.baidu.com/", "1498807162@qq.com"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }

}

此时通过浏览器访问http://localhost:8080/swagger-ui.html就可以查看端口信息，如果想要显示所有的接口信息，需要在Swaggerconfig中配置包扫描路径。

.Path()设置扫描请求路径，与扫描接口类似有几种不同方式。

配置文件中每配置一个Docket对象就生成一个分组，用.groupName()设置分组名字，再多人协同开发时，每个人有自己的Docket。

三、配置controlller注解，让SwaggerUI显示接口参数等各方面信息，实现代码生成接口文档
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数（Javabean 类上的注解）
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

上述注解只是给接口，参数，属性添加注释，生成的接口文档更友好而已，并无很高深的作用（只会MVC，一进公司发先项目里还有个API层，可把爷给整懵了）。

总结：
Swagger使用步骤：
1、引入Swagger2 与Swagger-UI包；
2、配置Swagger配置文件；（其中设置扫描路径是重点，容易扫不到，而且据说配置文件的位置也会影响扫描情况，最好在同级目录下或者父级）
3、给Controller层的类，方法，对象VO添加对应注解，使接口文档更友好；
4、项目正式上线后一定要关闭Swagger！！！！！！！！！
4、项目正式上线后一定要关闭Swagger！！！！！！！！！
4、项目正式上线后一定要关闭Swagger！！！！！！！！！

Swagger作用
1、使用代码自动生成接口文档，快速，高效，而且实时更新；
2、Swagger-UI上集成了PostMan的功能，前端可以在网页上调试接口！！！！