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”执行可以看到接口执行后的返回结果。