使用Swagger2实现RESTful文档

1 RESTful API

2.1 RESTful API的基本规范

/api/版本号/资源

（2）请求方法：

GET： 查询数据
POST： 提交新数据
PUT： 修改数据
DELETE： 删除数据

2.2 统一数据返回格式

（1）ApiResult：封装Api返回结果

public class ApiResult<T> {
 public ApiResult() {}
 public ApiResult(boolean ok, int code, T data, String message) {
 super();
 this.ok = ok;
 this.code = code;
 this.data = data;
 this.message = message;
 }
 //处理是否成功
 private boolean ok;
 //结果状态号，类比Http状态码
 private int code;
 //返回的结果数据
 private T data;
 //返回消息
 private String message;
 // 省略 getter 和 setter......
}

（2）ApiResultGenerator：提供工厂方法快速返回Api结果

public class ApiResultGenerator {
 private static final String DEFAULT_MESSAGE_SUCCESS = "SUCCESS"; //成功
 private static final String DEFAULT_MESSAGE_FAIL = "FAIL"; //失败
 private static final int RESULT_CODE_SUCCESS = 200; //成功
 private static final int RESULT_CODE_SERVER_ERROR = 500; //服务
 //...省略其它常量
 public static <T> ApiResult<T> success(T data){ //成功
 return new ApiResult<T>(true, RESULT_CODE_SUCCESS, data, DEFAULT_MESS
 }
 public static <T> ApiResult<T> success(){ //成功
 return new ApiResult<T>(true, RESULT_CODE_SUCCESS, null, DEFAULT_MESS
 }
 public static <T> ApiResult<T> error(String message){ //失败
 return new ApiResult<T>(false, RESULT_CODE_SERVER_ERROR, null, messag
 }
 public static <T> ApiResult<T> error(){ //失败
 return new ApiResult<T>(false, RESULT_CODE_SERVER_ERROR, null, DEFAUL
 }

2 Swagger-UI的使用

前后端分开开发中，前端人员需要异步调用后端发布的RESTful API服务，后端服务繁 多，清晰同步的API文档对于前端开发人员非常重要。Swagger是一款RESTful接口的文 档在线自动生成+功能测试功能软件。Spring可以非常方便的和Swagger集成，实现API 文档的自动生成和发布。

2.1 Swagger-UI 常用注解

详见：https://cloud.tencent.com/developer/article/1451907

2.2 Spring整合Swagger-UI （1）添加依赖

<!-- Swagger-UI -->
 <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>

 （2）配置Swagger 添加配置类：Swagger2Config.java

@Configuration
@EnableSwagger2
public class Swagger2Config {
 @Bean
public Docket createRestApi() {
 return new Docket(DocumentationType.SWAGGER_2)
 .apiInfo(apiInfo())
 .select()
 //为当前包下controller生成API文档
 .apis(RequestHandlerSelectors.basePackage("funnyshop.web.api"
 //为有@Api注解的Controller生成API文档
 .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
 //为有@ApiOperation注解的方法生成API文档
 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperati
 .paths(PathSelectors.any())
 .build();
 }
 private ApiInfo apiInfo() {
 return new ApiInfoBuilder()
 .title("FunnShop后端接口")
 .description("funnyshop-jee")
 .version("1.0")
 .build();
 }
}

 在SpringBoot启动类中启用Swagger

@MapperScan("funnyshop.mapper")
@SpringBootApplication
@EnableSwagger2 //启用Swagger2
public class FunnyshopJeeApplication {
 public static void main(String[] args) {
 SpringApplication.run(FunnyshopJeeApplication.class, args);
 }
}

（3）为RESTful API控制器标记文档

 （4）为数据对象标记文档

 （5）查看API文档 启动项目，访问：http://localhost:8080/swagger-ui.html

Swagger不仅提供查看文档功能，还可以直接测试，点击 “try it out!” 按钮即可。

            ------------------------------------------------------------------------------------------

@ApiOperation("根据商品名称模糊查询商品列表")
 @GetMapping("")
 @ApiImplicitParams({@ApiImplicitParam(name = "name", value="商品名称，模糊
 public List<Product> findByName(String name){
 return productBiz.findProducts(name);
 }