前后端分离技术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; } }
