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”可以进行测试。执行结果如下所示：