项目开发实现前后端分离，Swagger2是非常好用使用的一个框架！！！真香警告，个人感觉比Postman开发效率提升了很多，注解项会让代码更容易读
在后端开发中经常需要对移动客户端提供RESTful API接口，在后期版本快速迭代的过程中，修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，除非有严格的管理机制，不然很容易导致写出的代码与接口文档不一致现象。
为了前后台更好的对接,为了以后交接方便,为了不再长篇大论的手写api文档,那么就来用Swagger吧(不是打广告),它可以轻松的整合到Spring中,它既可以减少我们手写api文档的时间，同时又将说明文档整合到我们的代码中,这样前台看着也方便,后台工作也舒坦,
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单(其他好处网上自己搜在这里就不再多说了)。
Swagger也提供了强大的页面测试功能来调试每个写好的接口：
1.开发环境
- SpringBoot 2.0.4.RELEASE
- Swagger 2.6.1
- JDK 1.8
2.maven依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
3.Swagger2配置类（以下属于较为基本的属性配置，后期继续增加）
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class Swagger2Config {
@Bean
public Docket createDocket(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
.select().apis(RequestHandlerSelectors.basePackage("com.iflytek.studyproject.controller"))
.paths(PathSelectors.any()).build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder().title("Spring boot整合Swagger2学习")
.description("ApiInfo的描述")
.termsOfServiceUrl("no term url")
.version("1.0")
.build();
}
}@Configuration会被项目启动加载为配置类,等同于XML中配置的beans；@Bean标注方法等同于XML中配置的bean
4.启动类启动Swagger2（启动类中加入@EnableSwagger2 代表swagger开启:）
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootApplication
@EnableSwagger2
public class StudyprojectApplication {
public static void main(String[] args) {
SpringApplication.run(StudyprojectApplication.class, args);
}
}
5.定义Restful风格接口
import com.alibaba.fastjson.JSONObject;
import com.iflytek.studyproject.bean.Swagger2Bean;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/swagger2Controller")
public class Swagger2TestController {
@PostMapping("/getSwagger2")
public JSONObject getSwagger2(Swagger2Bean swagger2Bean){
JSONObject put = (JSONObject) new JSONObject().put(swagger2Bean.getId(), swagger2Bean.getName());
return put;
}
}
6.启动
启动项目访问 http://localhost:8080/swagger-ui.html
7.Swagger2常用注解
- @Api()用于类；
表示标识这个类是swagger的资源
- @ApiOperation()用于方法；
表示一个http请求的操作
- @ApiParam()用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等）
- @ApiModel()用于类
表示对类进行说明，用于参数用实体类接收
- @ApiModelProperty()用于方法，字段
表示对model属性的说明或者数据操作更改
- @ApiIgnore()用于类，方法，方法参数
表示这个方法或者类被忽略
- @ApiImplicitParam() 用于方法
表示单独的请求参数
- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
具体使用举例说明：
@Api()
用于类；表示标识这个类是swagger的资源
tags–表示说明
value–也是说明，可以使用tags替代
但是tags如果有多个值，会生成多个list