SpringBoot初探之Swagger配置

Swagger是一个用于描述和测试restful接口的工具，只要在定义restful接口时增加一些类和方法的描述注解，通过很简单的配置就可以得到一个展示接口定义的页面，也可以在页面上设置参数提交测试接口(替代postman的部分功能)。

接口修改后不需要单独修改描述文档，swagger自动生成接口文档。下面讲一下如果搭建一个最简单swagger测试Demo。

一、创建一个SpringBoot的maven项目

项目创建方式可以参考我这篇博客《Spring Boot初探之restful服务发布》，项目创建后的目录如下：

二、创建好后在pom.xml文件中增加swagger依赖的包

        <dependency> 
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

直接使用appache的仓库：

        <repository>  
            <id>springfox-swagger</id>  
            <url>https://mvnrepository.com/artifact/io.springfox/springfox-swagger2</url>  
        </repository>
        <repository>  
            <id>springfox-swagger-ui</id>  
            <url>https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui</url>  
        </repository>

三、添加swagger的配置加载类(Swagger2Config.java)

package com.elon.springbootdemo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

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 extends WebMvcConfigurerAdapter {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.elon.springbootdemo.ws"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(getApiInfo());
    }

    private ApiInfo getApiInfo()  
    {  
        ApiInfo apiInfo =  new ApiInfoBuilder().title("用户管理模块")
                .description("定义用户数据的增加、删除、修改接口")
                .termsOfServiceUrl("http://www.cnblogs.com/elon")
                .version("1.0")
                .build();
        return apiInfo;  
    }  
}

四、添加用于测试的restful接口(WSUserSwagger.java)

package com.elon.springbootdemo.ws;

import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

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

@RestController
@RequestMapping(value="swagger-demo")
@Api(value="WSUserSwagger", description="用户信息管理")
public class WSUserSwagger {

    @ApiOperation(value="添加用户", notes="添加用户")
    @RequestMapping(value="/v1/user", method=RequestMethod.POST)
    public String addUser(@RequestBody String userInfo) {
        return "Add user:" + userInfo;
    }

    @ApiOperation(value = "根据名称查询用户", notes = "根据名称查询用户")
    @RequestMapping(value = "/v1/user", method = RequestMethod.GET)
    public String queryUserByName(@RequestParam("name") String name, @RequestHeader("age") int age) {
        return name + age;
    }

    @ApiOperation(value="删除用户", notes="删除用户")
    @RequestMapping(value="/v1/user/{name}", method=RequestMethod.DELETE)
    public String deleteUser(@PathVariable("name") String name) {
        return "delete " + name;
    }
}

五、启动后测试

在浏览器中输入 http://localhost:8080/swagger-ui.html。打开页面可以看到定义的接口：

测试GET方法：点”Try it out”后输入参数， 点击”execute”执行可以看到接口执行后的返回结果。