Swagger的学习记录

本作者的Swagger学习历程

一、Swagger简介

官网：https://swagger.io/

1、什么是Swagger

Swagger 是一个用于生成、描述和调用 RESTful 接口的 Web 服务。通俗的来讲，Swagger 就是将项目中所有接口展现在页面上，并且可以进行接口调用和测试的服务。

2、什么是RESTful

简单的说：RESTful是一种架构的规范与约束、原则，符合这种规范的架构就是RESTful架构。

比如RESTful架构中对数据库的增删改查的请求方式进行了规范，

HTTP方法	数据库操作	描述
GET	SELECT	查找
POST	INSERT	添加
PUT	UPDATE	修改
DELETE	DELETE	删除

3、Swagger的作用

（1）将项目中所有的接口展现在页面上，不用再为前端工程师编写接口文档。
（2）避了接口文档老旧不能使用的问题，一旦程序运行起来，Swagger提供的接口就会实时更新。
（3）通过Swagger页面，可以对接口直接进行访问，降低了项目开发阶段的调试成本。

---

二、SpringBoot 集成 Swagger

1、在SpringBoot 项目中的pox.xml 中导入Swagger依赖（这里以2.9.2版本为例）。

	  	<!-- Swagger依赖 -->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger2</artifactId>
		<version>2.9.2</version>
	</dependency>
	
	<!-- Swagger的ui界面依赖 -->
	<dependency>
		<groupId>io.springfox</groupId>
		<artifactId>springfox-swagger-ui</artifactId>
		<version>2.9.2</version>
	</dependency>

2、创建包config，新建java类编写Swagger配置类

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

@Configuration//配置类
@EnableSwagger2//开启Swagger2
public class Swagger2Controller {
}

3、创建包controller，新建一个controller类HelloController

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
}

当我们写完Swager的配置类和controller接口后启动springboot程序，在浏览器中访问地址：http://localhost:8080/swagger-ui.html 即可进入Swagger提供的ui界面，在此界面中就可以看到我们编写的各种接口。

4、将接口信息修改成为我的信息，需要在SwaggerController类中修改

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

import java.util.ArrayList;

@Configuration//配置类
@EnableSwagger2//开启Swagger2
public class Swagger2Controller {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

        private ApiInfo apiInfo(){

        //作者信息
        Contact contact = new Contact("联系人姓名", "联系人访问地址", "联系人邮箱");

        return new ApiInfo(
                "文档标题",//文档标题
                "描述",//描述
                "1.0",//版本
                "组织url地址",//组织url地址
                contact,//联系人信息
                "Apache 2.0",//许可（不用改）
                "http://www.apache.org/licenses/LICENSE-2.0",//许可连接（不用改）
                new ArrayList()//扩展
        );
    }
}

再次启动springboot程序，访问：http://localhost:8080/swagger-ui.html，即可观察到Swagger的ui界面中的文档信息已经被我们修改成配置类中的信息了。

我们还能在apiInfo(apiInfo()) 的后面通过链式连接的方式设更多的Swagger属性

    @Bean
    public Docket docket(){
            return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())

            //groupName:配置分组
            .groupName("分组一")

            //通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了
//                .enable(false)

            .select()//通过.select()方法，去配置扫描接口

            //basePackage(final String basePackage):根据包路径扫描接口
            //any():扫描所有，项目中的所有接口都会被扫描到
            //none():不扫描接口
            //通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
            //通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
            // RequestHandlerSelectors配置如何扫描接口
            .apis(RequestHandlerSelectors.basePackage("要扫面的包路径"))

            //paths():过滤什么路径
            //配置如何通过path过滤,即这里只扫描请求以/xxu
            //any():任何请求都扫描
            //none():任何请求都不扫描
            //regex(final String pathRegex):通过正则表达式控制
            //ant(final String antPattern):通过ant()控制

//           .paths(PathSelectors.ant("/要过滤的路径名/**"))

            .build();
    }

上述属性设置，可以自行测试。

5、了解Swagger的ui界面右上角的分组

每一个分组中的接口信息都是由不同后端程序员编写的接口，所以设置分组的目的是可以清晰的知道这个接口是哪一位后端开发者编写的，此时在分组中只有一个默认的分组即default，接下来我们可以在Swagger的配置类中添加更多的Bean，通过groupName 给对应分组设置名字。

@Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("分组二");
    }

    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("分组三");
    }

    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("分组四");
    }

此时我们就可以看到ui界面中显示了在Swagger配置类中设置的四个分组。

6、ui界面中的实体类中如何展示我们定义的实体类。

如果只是简单的创建一个实体类，在我们的ui界面中并不会显示出我们的实体类信息。但是我们如果定义一个接口，该接口的返回值是我们定义的实体类，那么在ui界面中就会显示出该实体类的基本信息。

    //只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
    @PostMapping("/user")
    public User user(){
        return new User();
    }

启动springboot程序，访问ui界面就会发现实体类中多了我们自己定义的实体类基本信息。

7、通过Swagger提供的注解，为接口、实体类，添加基本的描述。

注解	描述
@Api	给实体类添加说明
@ApiModelProperty	给实体类中的属性添加说明
ApiOperation	给接口添加说明
@ApiParam	给接口中的属性添加说明

实体类

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

//@Api(注释):实体类
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户名")
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

Controller层

import com.xxu.pojo.User;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
    //只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
    @PostMapping("/user")
    public User user(){
        return new User();
    }

    //ApiOperation:接口，不是放在类上的，是方法上
    @ApiOperation("Hello控制类")
    @GetMapping("/hello2")
//    @ApiParam(描述):给属性添加描述
    public String hello2(@ApiParam("用户名") String username){
        return "hello" + username;
    }
}

8、利用Swagger的ui界面测试接口。

首先打开想要测试的接口，然后点击 try it out （尝试一下）

点击尝试一下后，再次点击Excute（尝试以下），

---

然后就可以看该接口的运行情况了。

以上就是作者对Swagger的一些见解，仅供参考！