springboot+swagger集成

一、swagger介绍

Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单

二、示例程序

1、新建maven工程springboot-swagger



2、引入springboot和swagger2的依赖

<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.springboot.swagger</groupId>
<artifactId>springboot-swagger</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>springboot-swagger</name>
<description>springboot-swagger</description>

<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.4.1.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.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
</dependencies>

</project>

3、新建springboot主运行类：

package com.springboot.swagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {

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

4、创建swagger配置类

package com.springboot.swagger.config;

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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket buildDocket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(ApiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.springboot.swagger.controller"))//该包下的类将会自动生成文档
.paths(PathSelectors.any())
.build();
}
private ApiInfo ApiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot+swagger2集成示例")
.contact("波神")
.version("1.0")
.build();
}
}

5、创建实体类

为Model(JSON)添加注释

package com.springboot.swagger.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("User(用户模型)")
public class User {

@ApiModelProperty("用户ID")
private Long id;
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("年龄")
private Integer age;

public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public Integer getAge() {
return age;
}
public void setAge(Integer age) {
this.age = age;
}
}

6、创建controller

package com.springboot.swagger.controller;

import java.util.HashMap;
import java.util.Map;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.springboot.swagger.model.User;

@RestController
@RequestMapping("/user")
@Api(value = "用户服务",description = "提供RESTful风格API的用户的增删改查服务")
public class UserController {
//模拟DAO层
private final Map<Long, User> repository = new HashMap<Long, User>();

@PostMapping("/add1")
@ApiOperation("添加用户")
public Boolean add1(@RequestBody User user) {
repository.put(user.getId(), user);
return true;
}

@PostMapping("/add2")
@ApiOperation("添加用户")
public Boolean add2(@ApiParam("用户信息")@RequestBody User user) {
repository.put(user.getId(), user);
return true;
}

@DeleteMapping("/{id}")
@ApiOperation("通过ID删除用户")
public Boolean delete(@PathVariable Long id) {
repository.remove(id);
return true;
}

@PutMapping
@ApiOperation("更新用户")
public Boolean update(@RequestBody User user) {
repository.put(user.getId(), user);
return true;
}

@GetMapping("/{id}")
@ApiOperation("通过ID查询用户")
public User findById(@PathVariable Long id) {
return repository.get(id);
}
}

@Api

注解用来表述该服务的信息，如果不使用则显示类名称.

@ApiOperation

注解用于表述接口信息

@ApiParam

注解用于描述接口的参数

上面之所以有add1和add2是为了说明，如果都是PostMapping类型，前端页面怎么来区分调用。

现在我们来启动它，执行

mvn spring-boot:run

，或直接运行

Application.main()

。

如是eclipse,可以右键项目，然后run as->java Application，在弹出来的对话框如下：



选择项目的Application然后选择ok

可以看到程序启动如下：

2017-05-09 16:44:51.457  INFO 39650 --- [           main] s.w.ClassOrApiAnnotationResourceGrouping : Group for method findById was 用户服务
2017-05-09 16:44:51.460  INFO 39650 --- [           main] s.w.ClassOrApiAnnotationResourceGrouping : Group for method findById was 用户服务
2017-05-09 16:44:51.464  INFO 39650 --- [           main] s.d.schema.ModelContextKeyGenerator      : Cache Key Generated: java.lang.Boolean(true)
2017-05-09 16:44:51.464  INFO 39650 --- [           main] s.d.spring.web.caching.CachingAspect     : Caching aspect applied for cache models with key java.lang.Boolean(true)
2017-05-09 16:44:51.465  INFO 39650 --- [           main] s.d.schema.ModelContextKeyGenerator      : Cache Key Generated: java.lang.Boolean(true)
2017-05-09 16:44:51.465  INFO 39650 --- [           main] s.d.spring.web.caching.CachingAspect     : Caching aspect applied for cache modelDependencies with key java.lang.Boolean(true)
2017-05-09 16:44:51.465  INFO 39650 --- [           main] s.d.schema.ModelContextKeyGenerator      : Cache Key Generated: com.springboot.swagger.model.User(false)
2017-05-09 16:44:51.465  INFO 39650 --- [           main] s.d.spring.web.caching.CachingAspect     : Caching aspect applied for cache models with key com.springboot.swagger.model.User(false)
2017-05-09 16:44:51.466  INFO 39650 --- [           main] s.d.schema.ModelContextKeyGenerator      : Cache Key Generated: com.springboot.swagger.model.User(false)
2017-05-09 16:44:51.466  INFO 39650 --- [           main] s.d.spring.web.caching.CachingAspect     : Caching aspect applied for cache modelDependencies with key com.springboot.swagger.model.User(false)
2017-05-09 16:44:51.466  INFO 39650 --- [           main] s.d.spring.web.OperationsKeyGenerator    : Cache key generated: /user.com.springboot.swagger.controller.UserController.update.DefaultGenericTypeNamingStrategy
2017-05-09 16:44:51.475  INFO 39650 --- [           main] s.d.spring.web.caching.CachingAspect     : Caching aspect applied for cache operations with key /user.com.springboot.swagger.controller.UserController.update.DefaultGenericTypeNamingStrategy
2017-05-09 16:44:51.480  INFO 39650 --- [           main] s.w.ClassOrApiAnnotationResourceGrouping : Group for method update was 用户服务
2017-05-09 16:44:51.483  INFO 39650 --- [           main] s.w.ClassOrApiAnnotationResourceGrouping : Group for method update was 用户服务
2017-05-09 16:44:51.658  INFO 39650 --- [           main] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 8080 (http)
2017-05-09 16:44:51.676  INFO 39650 --- [           main] com.springboot.swagger.Application       : Started Application in 9.276 seconds (JVM running for 9.745)

启动成功后，访问http://localhost:8080/swagger-ui.html，便可以看到我们刚才构建的计算服务的API文档了。



点开上面的，add1，点击下图当中的右边黄色部分，可以对参数进行修改。



然后点击“try it out”可以进行测试。执行结果如下所示：