Swagger简介以及SpringBoot整合Swagger（通俗易懂）

---

前言

在服务端开发过程中，开发人员往往会提供出来很多API接口供客户端开发人员使用，那么为了方便使用呢，开发人员会在开发接口的过程中同时维护一份文档，以说明每一个接口的访问方式、需要的参数、返回的结果等基本信息。
基于上述情况，诞生了许多API接口文档自动化生成工具，今天重点要说的就是其中的Swagger。

---

一、Swagger简介

Swagger说白了就是 Api框架，并且是号称当今世界上最流行的Api框架。（反正这东西就是必学呗）

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发。

作为一个开发人员，不管从事前端还是后端，Swagger可以说是必学了。

Swagger简介可以参考下这篇文章：https://www.jianshu.com/p/349e130e40d5

下面开始正文：

讲Swagger就要讲到前后端分离：

前后端分离
前端：完全脱离后端，前端独立开发，根据后端提供的接口可以事先设置一些假数据进行开发
后端：事先主要的控制层，业务逻辑，持久层，注重高可用，高并发，高扩展
前后端最后设置在不同的服务器上进行部署。
前后端分离开发是目前业界的web主流开发模式，所以两个组的文档设置就很重要，而swagger就是一个在线的接口API框架，支持多种语言。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

作用：
接口的文档在线自动生成。
功能测试。

Swagger是一组开源项目，其中主要要项目如下：

Swagger-tools: 提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成。
Swagger-js: 用于JavaScript的Swagger实现。
Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
Swagger-ui： 一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
Swagger-codegen： 一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

二、SpringBoot整合Swagger

1.新建一个SpringBoot Web项目

(新建SpringBoot项目的时候勾选上Spring Web即可)

注：记得配置下Maven和JDK的版本哦

没什么难度，傻瓜式操作，跳过~

2.导入依赖

如果前一步没有勾选上Spring Web这一步也可以手动导入Web的Maven依赖

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

我们导入2个Swagger相关的依赖：Swagger2和Swagger UI
代码如下：

        <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
        <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>

3.建立Swagger的配置文件

import org.springframework.context.annotation.Configuration;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2 // 开启Swagger2(开关)
public class SwaggerConfig {
}

我们先不对里面的值进行配置，它会有默认值的，先运行下看看结果。
启动SpringBoot之后访问：http://localhost:8080/swagger-ui.html

这个页面主要看这四部分的信息

4.在Swagger配置文件里配置ApiInfo

public class SwaggerConfig {
    //配置了Swagger的Docket实例
    @Bean
    public Docket docket(){
        return  new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    //配置Swagger信息——ApiInfo
    private  ApiInfo apiInfo(){
        //作者信息
        Contact contact = new Contact("BookSea", "https://blog.csdn.net/bookssea", "123456789@qq.com");
        return new ApiInfo(
                "码农BookSea_SwaggerAPI",
                "Api Documentation",
                "1.0",
                "https://blog.csdn.net/bookssea",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

上面的那个Contact的话，Swagger是有默认值的，不配置的话就是我们页面看到的那样，源码点进去我们可以看到

    static {
        DEFAULT = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }

即我们页面看到的那些信息，大家可以这些信息去一 一对应。

再次启动SpringBoot。访问：http://localhost:8080/swagger-ui.html#/
如下：

5.在Swagger配置文件里配置Docket实例

配置完了接口信息 ApiInfo我们再来配置下Docket实例。
如下：

相关的一些注释，我已经写上了，供大家参考

  public Docket docket(){
        return  new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //如果enable为false，则Swagger不能在浏览器中访问
//                .enable(false)
                .select()
                //RequestHandlerSelectors,配置扫描接口的方式
                //basePackage,指定要扫描的包
                //any,扫描全部
                //none,不扫描
                //withClassAnnotation,扫描类上的注解，参数是一个注解的反射对象
                //withMethodAnnotation,扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.example.springboot_swagger.controller"))
                //paths()。过滤什么路径
//                .paths(PathSelectors.ant("/example/**"))
                .build();

    }

配置完Docket实例之后，再写个接口

@RestController
public class HelloController {
    @RequestMapping(value = "/hello")
    public String hello(){
        return "hello";
    }
}

访问：http://localhost:8080/swagger-ui.html#/

这里有这么多的请求方式是因为我们没有指定@RequestMapping的请求方式，指定即可。

@RequestMapping(value = "/hello",method = RequestMethod.GET)

指定之后就OK啦，如下：

6.配置Swagger分组

起组名：

访问：http://localhost:8080/swagger-ui.html#/

配置Swagger分组
公司常常需要多人协同开发，多人协同开发的时候就需要多个分组

这些实例会被注入到IOC容器中。
访问端口，结果如下：

7.Swagger注解

我们再新建一个User实体类，并且完善一下接口，再添加上一些注解。
实体类

@ApiModel("用户类")   //给类添加说明
public class User {
    @ApiModelProperty("用户名")  //给参数添加说明
    public  String userName;
    @ApiModelProperty("密码")
    public  String password;

    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

控制层接口

@RestController
public class HelloController {
    //Operation接口
    @ApiOperation("访问hello")   //给接口添加说明
    @RequestMapping(value = "/hello",method = RequestMethod.GET)
    public String hello(  String name){
        return "您好,"+name;
    }

    @RequestMapping(value = "/user",method = RequestMethod.POST)
    public User user(User user){
        return user;
    }

}

常用的注解一般就这几个，后面我加上了注释。
访问看看效果

成功了~~，本篇文章就讲到这。