Spring Boot中使用Swagger2构建RESTful APIs

pom.xml文件

			
		
			io.springfox
			springfox-swagger2
			2.2.2
		
		
			io.springfox
			springfox-swagger-ui
			2.2.2
		

controller类

@RestController
@RequestMapping(value = "/api")
public class UserRestController {
	
	private  final Logger logger = LoggerFactory.getLogger(this.getClass());
	
	/**
	 * @ApiOperation注解来给API增加说明、通过@ApiImplicitParams注解来给参数增加说明。
	 * value 是标题,notes是详细说明
	 * @param user
	 * @return
	 */
	@ApiOperation(value="创建用户", notes="根据User对象创建用户")
    @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
	@PostMapping("/user")
    public boolean insert(@RequestBody User user) {
		logger.info("开始新增用户信息！请求参数:{}",user);
        return true;
    }
}

• 下列是Swagger的一些注解说明，更详细的可以查看官方的wiki文档。
  
      @Api：将类标记为Swagger资源。
      @ApiImplicitParam：表示API操作中的单个参数。
      @ApiImplicitParams：一个包装器，允许列出多个ApiImplicitParam对象。
      @ApiModel：提供有关Swagger模型的其他信息，比如描述POJO对象。
      @ApiModelProperty： 添加和操作模型属性的数据。
      @ApiOperation： 描述针对特定路径的操作或通常是HTTP方法。
      @ApiParam： 为操作参数添加其他元数据。
      @ApiResponse： 描述操作的可能响应。
      @ApiResponses： 一个包装器，允许列出多个ApiResponse对象。
      @Authorization： 声明要在资源或操作上使用的授权方案。
      @AuthorizationScope： 描述OAuth2授权范围。
      @ResponseHeader： 表示可以作为响应的一部分提供的标头。
      @ApiProperty： 描述POJO对象中的属性值。
      @ApiError ： 接口错误所返回的信息
      ...
  

  SpringBoot使用Swagger其实很简单，只需要在启动的时候添加@EnableSwagger2注解开启，然后再使用@Bean注解初始化一些相应的配置即可，比如编辑Swagger UI界面的信息，指定Swagger负责扫描的package等等。

• package com.pancm.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;
  
  /**
   * 
  * @Title: Swagger2
  * @Description: 
  * Swagger2配置
  * @Version:1.0.0  
  * @author pancm
  * @date 2018年5月29日
   */
  @Configuration
  @EnableSwagger2
  public class Swagger2 {
  
      @Bean
      public Docket createRestApi() {
          return new Docket(DocumentationType.SWAGGER_2)
                  .apiInfo(apiInfo())
                  .select()
                  .apis(RequestHandlerSelectors.basePackage("com.pancm"))
                  .paths(PathSelectors.any())
                  .build();
      }
  
      private ApiInfo apiInfo() {
          return new ApiInfoBuilder()
                  .title("Spring Boot中使用Swagger2构建RESTful APIs")
                  .description("测试")
                  .termsOfServiceUrl("http://www.panchengming.com/")
                  .contact("xuwujing")
                  .version("1.0")
                  .build();
      }
  
  }
  

  完成示例

•