前后端分离,Swagger框架
1.简介
随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、先后端分离的形态,而且前端技术和后端技术在各自的道路上越走越远。 前端和后端的唯一联系,变成了API接口;API文档变成了前后端开发人员联系的纽带,变得越来越重要,swagger就是一款让你更好的书写API文档的框架,而且swagger可以完全模拟http请求,入参出参和实际情况差别几乎为零。
没有API文档工具之前,大家都是手写API文档的(维护起来相当困难),在什么地方书写的都有,有在confluence上写的,有在对应的项目目录下readme.md上写的,每个公司都有每个公司的玩法,无所谓好坏。但是能称之为“框架”的,估计也只有swagger了
2.搭建项目
基于SpringBoot的
1.pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.3.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.yd</groupId>
<artifactId>demo_swagger</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>demo_swagger</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
<!-- swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
启动类
package com.yd;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication(scanBasePackages ="com.yd")
public class DemoSwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(DemoSwaggerApplication.class, args);
}
}
2.配置类
package com.yd.config;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket swaggerSpringMvcPlugin() {
return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();
}
}
3.Controller
package com.yd.controller;
import com.yd.pojo.ResObject;
import com.yd.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
@Api(description = "用户接口")
@RestController
@RequestMapping("/demoController")
public class DemoController {
@ApiOperation(value = "新增用户" , notes="新增注册")
@RequestMapping(value="/createUser",method= RequestMethod.POST,consumes= MediaType.APPLICATION_JSON_VALUE)
public ResObject createUser(@RequestBody User user){
System.out.println("createUser:::"+user.toString());
return new ResObject(HttpStatus.OK.value(), "新增成功.");
}
@ApiOperation(value = "修改用户" , notes="修改用户")
@RequestMapping(value="/updateUser",method=RequestMethod.POST,consumes= MediaType.APPLICATION_JSON_VALUE)
public ResObject updateUser(@RequestBody User user){
System.out.println("updateUser:::"+user.toString());
return new ResObject(HttpStatus.OK.value(), "修改成功.");
}
@ApiOperation(value = "删除用户" , notes="删除用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "query", dataType = "String")
})
@RequestMapping(value="/deleteUser",method=RequestMethod.DELETE)
public ResObject deleteUser(@RequestParam("userId") String userId){
System.out.println("deleteUser:::"+userId);
return new ResObject(HttpStatus.OK.value(), "删除成功.");
}
@ApiOperation(value = "查询用户" , notes="查询用户")
@ApiImplicitParams({
@ApiImplicitParam(name = "userId", value = "用户标识", required = true, paramType = "query", dataType = "String")
})
@RequestMapping(value="/queryUser",method=RequestMethod.GET)
public ResObject queryUser(@RequestParam("userId") String userId){
System.out.println("queryUser:::"+userId);
User user = new User(userId, "张三", "******", "[email protected]");
return new ResObject(HttpStatus.OK.value(), user);
}
}
4.User类
package com.yd.pojo;
public class User {
private String userId;
private String userName;
private String password;
private String email;
public User() {
super();
}
public User(String userId, String userName, String password, String email) {
super();
this.userId = userId;
this.userName = userName;
this.password = password;
this.email = email;
}
public String getUserId() {
return userId;
}
public void setUserId(String userId) {
this.userId = userId;
}
public String getUserName() {
return userName;
}
public void setUserName(String userName) {
this.userName = userName;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
public String getEmail() {
return email;
}
public void setEmail(String email) {
this.email = email;
}
}
5.ResObject类
package com.yd.pojo;
public class ResObject {
private int code;
private Object data;
private String desc;
public ResObject(int code, String desc) {
super();
this.code = code;
this.desc = desc;
}
public ResObject(int code, Object data) {
super();
this.code = code;
this.data = data;
}
public ResObject(int code, Object data, String desc) {
super();
this.code = code;
this.data = data;
this.desc = desc;
}
public int getCode() {
return code;
}
public void setCode(int code) {
this.code = code;
}
public String getDesc() {
return desc;
}
public void setDesc(String desc) {
this.desc = desc;
}
public Object getData() {
return data;
}
public void setData(Object data) {
this.data = data;
}
}