Spring Boot多模块项目 整合Swagger2

LoveEmperor-王子様
本人项目demo（spring boot多模块）：https://github.com/LoveEmperor/iproject
转载：https://blog.csdn.net/saytime/article/details/74937664

相信各位在公司写API文档数量应该不少，当然如果你还处在自己一个人开发前后台的年代，当我没说，如今为了前后台更好的对接，还是为了以后交接方便，都有要求写API文档。

手写Api文档的几个痛点：

1. 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
2. 接口返回结果不明确
3. 不能直接在线测试接口，通常需要使用工具，比如postman
4. 接口文档太多，不好管理

Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

其他的不多说，想要了解Swagger的，可以去Swagger官网，可以直接使用Swagger editor编写接口文档，当然我们这里讲解的是SpringBoot整合Swagger2，直接生成接口文档的方式。

一、依赖

    
    
<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>
    
    

二、Swagger配置类

其实这个配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径，不然生成的文档扫描不到接口。

    
    
package cn.saytime;

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;

/**
* @author zh
* @ClassName cn.saytime.Swgger2
* @Description
* @date 2017-07-10 22:12:31
*/
@Configuration
public class Swagger2 {

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage( "cn.saytime.web"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title( "springboot利用swagger构建api文档")
.description( "简单优雅的restfun风格，http://blog.csdn.net/saytime")
.termsOfServiceUrl( "http://blog.csdn.net/saytime")
.version( "1.0")
.build();
}
}
    
    

用@Configuration注解该类，等价于XML中配置beans；用@Bean标注方法等价于XML中配置bean。

Application.class 加上注解@EnableSwagger2 表示开启Swagger

    
    
package cn.saytime;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SpringbootSwagger2Application {

public static void main(String[] args) {
SpringApplication.run(SpringbootSwagger2Application. class, args);
}
}
    
    

三、Restful 接口

    
    
package cn.saytime.web;

import cn.saytime.bean.JsonResult;
import cn.saytime.bean.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.ResponseEntity;
import org.springframework.web.bind. annotation.PathVariable;
import org.springframework.web.bind. annotation.RequestBody;
import org.springframework.web.bind. annotation.RequestMapping;
import org.springframework.web.bind. annotation.RequestMethod;
import org.springframework.web.bind. annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
* @author zh
* @ClassName cn.saytime.web.UserController
* @Description
*/
@RestController
public class UserController {

// 创建线程安全的Map
static Map<Integer, User> users = Collections.synchronizedMap( new HashMap<Integer, User>());

/**
* 根据ID查询用户
* @param id
* @return
*/
@ApiOperation (value= "获取用户详细信息" , notes= "根据url的id来获取用户详细信息" )
@ApiImplicitParam (name = "id" , value = "用户ID" , required = true , dataType = "Integer" , paramType = "path" )
@RequestMapping (value = "user/{id}" , method = RequestMethod.GET)
public ResponseEntity<JsonResult> getUserById ( @PathVariable (value = "id" ) Integer id){
JsonResult r = new JsonResult();
try {
User user = users. get(id);
r.setResult(user);
r.setStatus( "ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus( "error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}

/**
* 查询用户列表
* @return
*/
@ApiOperation (value= "获取用户列表" , notes= "获取用户列表" )
@RequestMapping (value = "users" , method = RequestMethod.GET)
public ResponseEntity<JsonResult> getUserList (){
JsonResult r = new JsonResult();
try {
List<User> userList = new ArrayList<User>(users.values());
r.setResult(userList);
r.setStatus( "ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus( "error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}

/**
* 添加用户
* @param user
* @return
*/
@ApiOperation (value= "创建用户" , notes= "根据User对象创建用户" )
@ApiImplicitParam (name = "user" , value = "用户详细实体user" , required = true , dataType = "User" )
@RequestMapping (value = "user" , method = RequestMethod.POST)
public ResponseEntity<JsonResult> add ( @RequestBody User user){
JsonResult r = new JsonResult();
try {
users.put(user.getId(), user);
r.setResult(user.getId());
r.setStatus( "ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus( "error");

e.printStackTrace();
}
return ResponseEntity.ok(r);
}

/**
* 根据id删除用户
* @param id
* @return
*/
@ApiOperation (value= "删除用户" , notes= "根据url的id来指定删除用户" )
@ApiImplicitParam (name = "id" , value = "用户ID" , required = true , dataType = "Long" , paramType = "path" )
@RequestMapping (value = "user/{id}" , method = RequestMethod.DELETE)
public ResponseEntity<JsonResult> delete ( @PathVariable (value = "id" ) Integer id){
JsonResult r = new JsonResult();
try {
users.remove(id);
r.setResult(id);
r.setStatus( "ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus( "error");

e.printStackTrace();
}
return ResponseEntity.ok(r);
}

/**
* 根据id修改用户信息
* @param user
* @return
*/
@ApiOperation (value= "更新信息" , notes= "根据url的id来指定更新用户信息" )
@ApiImplicitParams ({
@ApiImplicitParam (name = "id" , value = "用户ID" , required = true , dataType = "Long" ,paramType = "path" ),
@ApiImplicitParam (name = "user" , value = "用户实体user" , required = true , dataType = "User" )
})
@RequestMapping (value = "user/{id}" , method = RequestMethod.PUT)
public ResponseEntity<JsonResult> update ( @PathVariable ( "id" ) Integer id, @RequestBody User user){
JsonResult r = new JsonResult();
try {
User u = users. get(id);
u.setUsername(user.getUsername());
u.setAge(user.getAge());
users.put(id, u);
r.setResult(u);
r.setStatus( "ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus( "error");

e.printStackTrace();
}
return ResponseEntity.ok(r);
}

@ApiIgnore //使用该注解忽略这个API
@RequestMapping (value = "/hi" , method = RequestMethod.GET)
public String jsonTest() {
return " hi you!";
}
}
    
    

Json格式输出类 JsonResult.class

扫描二维码关注公众号，回复： 1874461 查看本文章

    
    
package cn.saytime.bean;

public class JsonResult {

private String status = null;

private Object result = null;

// Getter Setter
}
    
    

实体User.class

    
    
package cn.saytime.bean;

import java.util.Date;

/**
* @author zh
* @ClassName cn.saytime.bean.User
* @Description
*/
public class User {

private int id;
private String username;
private int age;
private Date ctm;

// Getter Setter
}
    
    

项目结构：

四、Swagger2文档

启动SpringBoot项目，访问 http://localhost:8080/swagger-ui.html

具体里面的内容以及接口测试，应该一看就懂了。这里就不一一截图了。

五、Swagger注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：一个请求参数
• @ApiImplicitParams：多个请求参数

            </div>

相信各位在公司写API文档数量应该不少，当然如果你还处在自己一个人开发前后台的年代，当我没说，如今为了前后台更好的对接，还是为了以后交接方便，都有要求写API文档。

手写Api文档的几个痛点：

1. 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
2. 接口返回结果不明确
3. 不能直接在线测试接口，通常需要使用工具，比如postman
4. 接口文档太多，不好管理

Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

其他的不多说，想要了解Swagger的，可以去Swagger官网，可以直接使用Swagger editor编写接口文档，当然我们这里讲解的是SpringBoot整合Swagger2，直接生成接口文档的方式。

一、依赖

  
  
<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>
  
  

二、Swagger配置类

其实这个配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径，不然生成的文档扫描不到接口。

  
  
package cn.saytime;

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;

/**
* @author zh
* @ClassName cn.saytime.Swgger2
* @Description
* @date 2017-07-10 22:12:31
*/
@Configuration
public class Swagger2 {

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage( "cn.saytime.web"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title( "springboot利用swagger构建api文档")
.description( "简单优雅的restfun风格，http://blog.csdn.net/saytime")
.termsOfServiceUrl( "http://blog.csdn.net/saytime")
.version( "1.0")
.build();
}
}
  
  

用@Configuration注解该类，等价于XML中配置beans；用@Bean标注方法等价于XML中配置bean。

Application.class 加上注解@EnableSwagger2 表示开启Swagger

  
  
package cn.saytime;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SpringbootSwagger2Application {

public static void main(String[] args) {
SpringApplication.run(SpringbootSwagger2Application. class, args);
}
}
  
  

三、Restful 接口

  
  
package cn.saytime.web;

import cn.saytime.bean.JsonResult;
import cn.saytime.bean.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.ResponseEntity;
import org.springframework.web.bind. annotation.PathVariable;
import org.springframework.web.bind. annotation.RequestBody;
import org.springframework.web.bind. annotation.RequestMapping;
import org.springframework.web.bind. annotation.RequestMethod;
import org.springframework.web.bind. annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
* @author zh
* @ClassName cn.saytime.web.UserController
* @Description
*/
@RestController
public class UserController {

// 创建线程安全的Map
static Map<Integer, User> users = Collections.synchronizedMap( new HashMap<Integer, User>());

/**
* 根据ID查询用户
* @param id
* @return
*/
@ApiOperation (value= "获取用户详细信息" , notes= "根据url的id来获取用户详细信息" )
@ApiImplicitParam (name = "id" , value = "用户ID" , required = true , dataType = "Integer" , paramType = "path" )
@RequestMapping (value = "user/{id}" , method = RequestMethod.GET)
public ResponseEntity<JsonResult> getUserById ( @PathVariable (value = "id" ) Integer id){
JsonResult r = new JsonResult();
try {
User user = users. get(id);
r.setResult(user);
r.setStatus( "ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus( "error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}

/**
* 查询用户列表
* @return
*/
@ApiOperation (value= "获取用户列表" , notes= "获取用户列表" )
@RequestMapping (value = "users" , method = RequestMethod.GET)
public ResponseEntity<JsonResult> getUserList (){
JsonResult r = new JsonResult();
try {
List<User> userList = new ArrayList<User>(users.values());
r.setResult(userList);
r.setStatus( "ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus( "error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}

/**
* 添加用户
* @param user
* @return
*/
@ApiOperation (value= "创建用户" , notes= "根据User对象创建用户" )
@ApiImplicitParam (name = "user" , value = "用户详细实体user" , required = true , dataType = "User" )
@RequestMapping (value = "user" , method = RequestMethod.POST)
public ResponseEntity<JsonResult> add ( @RequestBody User user){
JsonResult r = new JsonResult();
try {
users.put(user.getId(), user);
r.setResult(user.getId());
r.setStatus( "ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus( "error");

e.printStackTrace();
}
return ResponseEntity.ok(r);
}

/**
* 根据id删除用户
* @param id
* @return
*/
@ApiOperation (value= "删除用户" , notes= "根据url的id来指定删除用户" )
@ApiImplicitParam (name = "id" , value = "用户ID" , required = true , dataType = "Long" , paramType = "path" )
@RequestMapping (value = "user/{id}" , method = RequestMethod.DELETE)
public ResponseEntity<JsonResult> delete ( @PathVariable (value = "id" ) Integer id){
JsonResult r = new JsonResult();
try {
users.remove(id);
r.setResult(id);
r.setStatus( "ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus( "error");

e.printStackTrace();
}
return ResponseEntity.ok(r);
}

/**
* 根据id修改用户信息
* @param user
* @return
*/
@ApiOperation (value= "更新信息" , notes= "根据url的id来指定更新用户信息" )
@ApiImplicitParams ({
@ApiImplicitParam (name = "id" , value = "用户ID" , required = true , dataType = "Long" ,paramType = "path" ),
@ApiImplicitParam (name = "user" , value = "用户实体user" , required = true , dataType = "User" )
})
@RequestMapping (value = "user/{id}" , method = RequestMethod.PUT)
public ResponseEntity<JsonResult> update ( @PathVariable ( "id" ) Integer id, @RequestBody User user){
JsonResult r = new JsonResult();
try {
User u = users. get(id);
u.setUsername(user.getUsername());
u.setAge(user.getAge());
users.put(id, u);
r.setResult(u);
r.setStatus( "ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus( "error");

e.printStackTrace();
}
return ResponseEntity.ok(r);
}

@ApiIgnore //使用该注解忽略这个API
@RequestMapping (value = "/hi" , method = RequestMethod.GET)
public String jsonTest() {
return " hi you!";
}
}
  
  

Json格式输出类 JsonResult.class

  
  
package cn.saytime.bean;

public class JsonResult {

private String status = null;

private Object result = null;

// Getter Setter
}
  
  

实体User.class

  
  
package cn.saytime.bean;

import java.util.Date;

/**
* @author zh
* @ClassName cn.saytime.bean.User
* @Description
*/
public class User {

private int id;
private String username;
private int age;
private Date ctm;

// Getter Setter
}
  
  

项目结构：

四、Swagger2文档

启动SpringBoot项目，访问 http://localhost:8080/swagger-ui.html

具体里面的内容以及接口测试，应该一看就懂了。这里就不一一截图了。

五、Swagger注解

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：一个请求参数
• @ApiImplicitParams：多个请求参数

            </div>