2019独角兽企业重金招聘Python工程师标准>>> 
一、Swagger的产生
我们的RESTfulAPI需要面对多个开发人员或多个开发团队：
IOS开发、Android开发或是Web开发等。
为了减少与其他团队平时开发期间的频繁沟通成本，传统做法我们会创建一份RESTfulAPI文档来记录所有接口细节，
然而这样的做法有以下几个问题：
由于接口众多，并且细节复杂（需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等），
高质量地创建这份文档本身就是件非常吃力的事，下游的抱怨声不绝于耳。
随着时间推移，不断修改接口实现的时候都必须同步修改接口文档，而文档与代码又处于两个不同的媒介，
除非有严格的管理机制，不然很容易导致不一致现象。
手写Api文档的几个痛点：
文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时
接口返回结果不明确
不能直接在线测试接口，通常需要使用工具，比如postman
接口文档太多，不好管理
Swagger的产生就是为了解决以上这些问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。
二、Swagger的介绍
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
总体目标是使客户端和文件系统作为服务器以同样的速度来更新。
文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
Swagger 让部署管理和使用功能强大的API从未如此简单。
接下来我们介绍spring boot怎么集成swagger。
三、使用Idea新建一个spring boot 项目 然后选中Web依赖
1、依赖
2、Swagger配置类
其实这个配置类，只要了解具体能配置哪些东西就好了，毕竟这个东西配置一次之后就不用再动了。 特别要注意的是里面配置了api文件也就是controller包的路径，不然生成的文档扫描不到接口。
package com.example.springbootswagger2.config;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
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;
@Configuration
public class Swagger2Config {
private Logger log = LoggerFactory.getLogger(Swagger2Config.class);
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//扫描所有有注解的api，用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//.apis(RequestHandlerSelectors.basePackage("com.example.springbootswagger2.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("springboot利用swagger构建api文档")
.description("简单优雅的restfun风格，http://blog.csdn.net/saytime")
.termsOfServiceUrl("http://blog.csdn.net/saytime")
.version("1.0")
.build();
}
}
用@Configuration注解该类，等价于XML中配置beans；用@Bean标注方法等价于XML中配置bean。
Application.class 加上注解@EnableSwagger2 表示开启Swagger
3、Restful 接口
package com.example.springbootswagger2.controller;
import com.example.springbootswagger2.bean.JsonResult;
import com.example.springbootswagger2.bean.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
import java.util.*;
/**
* @author zh
* @ClassName cn.saytime.web.UserController
* @Description
*/
@RestController
public class UserController {
// 创建线程安全的Map
static Map
/**
* 根据ID查询用户
*
* @param id
* @return
*/
@ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
@RequestMapping(value = "user/{id}", method = RequestMethod.GET)
public ResponseEntity
JsonResult r = new JsonResult();
try {
User user = users.get(id);
r.setResult(user);
r.setStatus("ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}
/**
* 查询用户列表
*
* @return
*/
@ApiOperation(value = "获取用户列表", notes = "获取用户列表")
@RequestMapping(value = "users", method = RequestMethod.GET)
public ResponseEntity
JsonResult r = new JsonResult();
try {
List
r.setResult(userList);
r.setStatus("ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}
/**
* 添加用户
*
* @param user
* @return
*/
@ApiOperation(value = "创建用户", notes = "根据User对象创建用户")
@ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")
@RequestMapping(value = "user", method = RequestMethod.POST)
public ResponseEntity
JsonResult r = new JsonResult();
try {
users.put(user.getId(), user);
r.setResult(user.getId());
r.setStatus("ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}
/**
* 根据id删除用户
*
* @param id
* @return
*/
@ApiOperation(value = "删除用户", notes = "根据url的id来指定删除用户")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
@RequestMapping(value = "user/{id}", method = RequestMethod.DELETE)
public ResponseEntity
JsonResult r = new JsonResult();
try {
users.remove(id);
r.setResult(id);
r.setStatus("ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}
/**
* 根据id修改用户信息
*
* @param user
* @return
*/
@ApiOperation(value = "更新信息", notes = "根据url的id来指定更新用户信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path"),
@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")
})
@RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
public ResponseEntity
JsonResult r = new JsonResult();
try {
User u = users.get(id);
u.setUsername(user.getUsername());
u.setAge(user.getAge());
users.put(id, u);
r.setResult(u);
r.setStatus("ok");
} catch (Exception e) {
r.setResult(e.getClass().getName() + ":" + e.getMessage());
r.setStatus("error");
e.printStackTrace();
}
return ResponseEntity.ok(r);
}
@ApiIgnore//使用该注解忽略这个API
@RequestMapping(value = "/hi", method = RequestMethod.GET)
public String jsonTest() {
return " hi you!";
}
}
4、Json格式输出类 JsonResult
package com.example.springbootswagger2.bean;
public class JsonResult {
private String status = null;
private Object result = null;
// Getter Setter
}
5、实体User
package com.example.springbootswagger2.bean;
import java.util.Date;
public class User {
private int id;
private String username;
private int age;
private Date ctm;
// Getter Setter
}
6、Swagger2文档
启动SpringBoot项目，访问 http://localhost:8080/swagger-ui.html
swagger-bootstrap-ui默认访问地址是：http://localhost:8080/doc.html
7、注意事项
swagger封装给出的请求地址默认是/v2/api-docs,所以swagger-bootstrap-ui调用后台也是/v2/api-docs
不能带后缀,且需返回json格式数据,框架如果是spring boot的可以不用修改,直接使用
四、Swagger注解
swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。
@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数