前后端分离技术Swagger

一、提出问题

在前后端分离开发的过程中，前端和后端需要进行api对接进行交互，就需要一个api规范文档，方便前后端的交互，但api文档不能根据代码的变化发生实时动态的改变，这样后端修改了接口，前端不能及时获取最新的接口，导致调用出错，需要手动维护api文档，加大了开发的工作量和困难，而swagger的出现就是为了解决这一系列的问题。

二、swagger的介绍

swagger是一套基于OpenAPI规范构建的开源工具，使用RestApi

1、代码变，文档变

2、跨语言，支持多种语言

3、swagger-ui 呈现出来的是一份可交互式的API文档，可以直接在文档页面尝试API的调用

4、可以将文档规范导入相关工具（postman、soapui），这些工具将会为我们自动地创建自动化测试

补充：

RestApi格式是根据请求的方式决定本次请求的一个操作，譬如：get-->读，post-->写（增、删、改），put-->修改，delete-->删除
OpenApi与语言无关，只是一种规范，可以使用yaml和json格式进行编写，这样更利于我们和机器进行阅读

swagger主要包含了以下三个部分：

swagger editor：基于浏览器的编辑器，我们可以使用它编写我们OpenApi规范(yaml或者json配置）

Swagger UI：他会将我们编写的OpenApi规范呈现为交互式的API文档，后文我将使用浏览器来查看并且操作我们的RestApi

Swagger Codegen：它可以通过OpenApi规范定义的任何API生成服务器存根和客户端SDK来简化构建过程

使用swagger就是把相关信息存储在它定义的描述文件里面（yml或json格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码

三、springfox介绍

使用swagger时如果碰见版本更新迭代时，只需要更改swagger的描述文件即可，但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件（yml或json文件）也是一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成接口文档也失去了意义。

Marty Pitt编写了一个基于spring的组件swagger-springmvc,Spring-fox就是根据这个组件发展而来的全新项目;

Spring-fox是根据代码生成接口文档，所以正常的进行更新项目版本，修改代码即可，而不需要跟随修改描述文件(yml或json文件）;

spring-fox利用自身AOP特性，把swagger集成进来，底层还是Swagger，但是使用起来却方便很多，所以在实际开发中，都是直接使用spring-fox。

四 Swagger官网

API Documentation & Design Tools for Teams | Swagger

五 Swagger依赖的官网地址

https://mvnrepository.com/search?q=Springfox-swag 下面是从官网中找到的依赖

   <!-- 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>

Swagger程序的配置信息:

package com.hu.swagger.config;
import org.omg.CORBA.Environment;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
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;
import java.util.ArrayList;
@Configuration
@EnableSwagger2 //打开swagger2
//配置完毕
public class SwaggerConfig {
}

swagger的基础信息配置-->config类

@Configuration
@EnableSwagger2 //开启swagger2,若启动类上添加了该注解，则配置类可以不添加
public class SwaggerConfig {
    // 创建swagger bean
    @Bean
    public Docket docket() {
        // Docket是swagger全局配置对象
        // DocumentationType：指定文档类型为swagger2
        return new Docket(DocumentationType.SWAGGER_2)
                // swagger信息
                .apiInfo(apiInfo());
    }
    // swagger文档信息
    public ApiInfo apiInfo() {
        // 作者信息
        Contact contact = new Contact(
                // 文档发布者的名称
                "iqiuq",
                // 文档发布者的网站地址
                "https://iqiuq.gitee.io/qiuqblogs/",
                // 文档发布者的电子邮箱
                "qiuyonghui258@163.com"
        );
        return new ApiInfo(
                // 标题
                "iqiuq swagger api",
                // 文档描述
                "演好自己人生的剧本",
                // 版本号
                "1.0",
                // 服务组url地址
                "urn:tos", 
                // 作者信息
                contact,
                // 开源组织
                "Apache 2.0",
                // 开源地址
                "http://www.apache.org/licenses/LICENSE-2.0",
                // 集合
                new ArrayList()
        );
    }
}

SwaggerBean管理

 //SwaggerBean实例
    @Bean
    public Docket docket() {
        //获取项目环境 返回dev
//        Profile profile =Profile.of("dev","test");
//      boolean b=  environment.acceptsProfiles();
        //配置Swagger
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("小胡")
//     enable(false)  是否启动了Swagger
//                .enable(true)
                .select()
                //RequestHandlerSelectors 扫描的接口包
                //basePackage指定扫描的包名
                //.any 扫描全部包名
                //。none 不扫描
                //。withClassAnnotation  扫描类上的注解
                //withMethodAnnotation 扫描方法注解
                //.(RestController.class) 扫描类上的有RestController的类
                .apis(RequestHandlerSelectors.basePackage("com.hu.swagger.Controller"))
                .paths(PathSelectors.ant("/hu/**"))     //过滤
                .build();//工程模式
    }

配置 Swagger apiInfo 类

private ApiInfo apiInfo() {
        //作者信息
        Contact contact = new springfox.documentation.service.Contact("hubin", "http://www", "12345");
        return new ApiInfo("Api Documentation",
                "Api Documentation",
                "1.0",
                "urn:tos",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }

多个角色如何执行

@Configuration
@EnableSwagger2 //打开swagger2
//配置完毕
public class SwaggerConfig {
//多个角色
    @Bean
    public  Docket docket11(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");
    }
    @Bean
    public  Docket docket12(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");
    }
    @Bean
    public  Docket docket13(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");
    }
    @Bean
    public  Docket docket14(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("D");
    }
    @Bean
    public  Docket docket15(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("E");
    }

Swagger注解:swagger注解主要是用来给swagger生成的接口文档说明用的

package com.hu.swagger.pojo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
//@Api 注释
//生成注释
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("/用户名")
    private String username;
    @ApiModelProperty("/密码")
    private String password;
}

package com.hu.swagger.Controller;
import com.hu.swagger.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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
//Operation 接口注释
@ApiOperation("Hellow Controller注释信息")
@RestController
public class Hellow {
    @GetMapping(value = "/hello")
    public String hellow() {
        return "<h1>hellow Word Swagger<h1>";
    }
    //    只要我们的接口中 返回值存在
    @PostMapping(value = "/user")
    public User user() {
        return new User();
    }
    //    Operation 接口注释
    @ApiOperation("Hellow 控制类")
    @GetMapping(value = "/hello2")
    public String hellow2(@ApiParam("用户名") String username) {
        return "<h1>hellow2 Word Swagger<h1>"+username;
    }
    //    Operation 接口注释
    @ApiOperation("Hellow 控制类")
    @GetMapping(value = "/hello2")
    public String hellow3( String username) {
        return "<h1>hellow2 Word Swagger<h1>"+username;
    }
}

前后端分离技术(课时二十四)