介绍
发现了痛点就要去找解决方案。解决方案用的人多了,就成了标准的规范,这就是Swagger的由来。通过这套规范,你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。
但即便如此,对于许多开发来说,编写这个yml或json格式的描述文件,本身也是有一定负担的工作,特别是在后面持续迭代开发的时候,往往会忽略更新这个描述文件,直接更改代码。久而久之,这个描述文件也和实际项目渐行渐远,基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring,迅速将Swagger规范纳入自身的标准,建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。
使用
1.在pom.xml创建swagger依赖
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency>
2.配置swagger-config
@Configuration @EnableSwagger2 public class SwaggerConfig { }
3.测试运行
4.首页功能介绍
5.配置swagger的docket实例
//配置swagger的docket的bean实例 @Bean public Docket docket(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .groupName("大浩浩"); } //配置swagger信息=apiInfo private ApiInfo apiInfo(){ //作者信息 Contact contact = new Contact("大浩浩","https://www.dhhblog.com/?p=1351","2638723350@qq.com"); return new ApiInfo( "浩浩的swagger日记", "这个作者有点吊", "v1.0", "https://www.dhhblog.com/?p=1351", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); }
6.添加models
domain目录下创建user类
public class User { private int id; private String username; private String pwd; }
controller目录下创建HelloController类
@RestController public class HelloController { @PostMapping("/user") public User user(){ return new User(); } }
打开网址会看到user
7.实体类添加注解
首页会提示注释,更加直观
8.创建测试接口
编辑HelloController类
package net.xdclass.demoproject.controller; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import net.xdclass.demoproject.domain.User; 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(value = "hello") public String hello(){ return "hello"; } @PostMapping("/user") public User user(){ return new User(); } //operation接口不是放在类上的,是方法 @ApiOperation("hello控制类") @GetMapping(value = "/hello2") //@ApiParam添加注释 public String hello2(@ApiParam("用户名") String username){ return "hello"+username; } @ApiOperation("Post测试类") @PostMapping(value = "/postt") public User postt(@ApiParam("用户名") User user){ return user; } }
写好接口打开网址即可看到所有接口
9.post请求提交测试
测试结果