- API接口众多，细节复杂，需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等，想要高质量的完成这份文档需要耗费大量的精力。
- 难以维护：随着需求的变更和项目的优化、推进，接口的细节在不断地演变，接口描述文档也需要同步修订，可是文档和代码处于两个不同的媒介，除非有严格的管理机制，否则很容易出现文档、接口不一致的情况。
- Swagger2 的出现就是为了从根本上解决上述问题。
- 一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务：
- 接口文档在线自动生成，文档随接口变动实时更新，节省维护成本。
- 支持在线接口测试，不依赖第三方工具。
package com.programb;import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;@SpringBootApplication
public class Swagger2AutoApplication {public static void main(String[] args) {SpringApplication.run(Swagger2AutoApplication.class, args);}
}
package com.programb.config;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
@Profile({"dev","programb"})public class Swagger2Config {@Beanpublic Docket controllerApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(new ApiInfoBuilder().title("programb").description("programb").contact(new Contact("programb", null, null)).version("programb").build()).select().apis(RequestHandlerSelectors.basePackage("com.programb.controller")).paths(PathSelectors.any()).build();}
}
package com.programb.controller;import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import com.programb.entity.User;
import springfox.documentation.annotations.ApiIgnore;
import java.util.ArrayList;
import java.util.List;@Api("用户信息管理")
@RestController
@RequestMapping("/user/*")
public class UserController {private final static List<User> userList = new ArrayList<>();{userList.add(new User("1", "admin", "123456"));userList.add(new User("2", "programb", "100000"));}@ApiOperation("获取列表")@GetMapping("list")public List userList() {return userList;}@ApiOperation("新增用户")@PostMapping("save")public boolean save(User user) {return userList.add(user);}@ApiOperation("更新用户")@ApiImplicitParam(name = "user", value = "用户信息", dataType = "User")@PutMapping("update")public boolean update(User user) {return userList.remove(user) && userList.add(user);}@ApiOperation("批量删除")@ApiImplicitParam(name = "users", value = "用户信息", dataType = "List<User>")@DeleteMapping("delete")public boolean delete(@RequestBody List<User> users) {return userList.removeAll(users);}
}
package com.programb.entity;public class User {private String userId;private String username;private String password;public User() {}public User(String userId, String username, String password) {this.userId = userId;this.username = username;this.password = password;}@Overridepublic boolean equals(Object o) {if (this == o) {return true;}if (o == null || getClass() != o.getClass()) {return false;}User user = (User) o;return userId != null ? userId.equals(user.userId) : user.userId == null;}@Overridepublic int hashCode() {int result = userId != null ? userId.hashCode() : 0;result = 31 * result + (username != null ? username.hashCode() : 0);result = 31 * result + (password != null ? password.hashCode() : 0);return result;}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;}
}
server:port: 8081swagger.enable: true
server:port: 8082
spring:profiles:active: prod
<?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><groupId>com.programb</groupId><artifactId>springboot-swagger2-auto-close</artifactId><version>0.0.1-SNAPSHOT</version><packaging>jar</packaging><name>spring-boot-swagger2-auto-close</name><description>SpringBoot-Swagger</description><parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.0.3.RELEASE</version></parent><dependencies><dependency> <groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.7.0</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.7.0</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency></dependencies><repositories><repository><id>spring-snapshots</id><url>http://repo.spring.io/snapshot</url><snapshots><enabled>true</enabled></snapshots></repository><repository><id>spring-milestones</id><url>http://repo.spring.io/milestone</url></repository></repositories><pluginRepositories><pluginRepository><id>spring-snapshots</id><url>http://repo.spring.io/snapshot</url></pluginRepository><pluginRepository><id>spring-milestones</id><url>http://repo.spring.io/milestone</url></pluginRepository></pluginRepositories><build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>
</project>
