swagger使用及源码分析

Swagger 是一个用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。Swagger 让部署管理和使用功能强大的API从未如此简单。
下面会从基本原理、如何使用(基于spring-mvc)、常用注解 、源码分析四个部分进行分析.

基本原理

web开发过程中，api定义是前后端交互最基本也是最重要的信息，而在实践过程中，往往是更新了代码，而没有来得及更新aip，导致api与代码不对应，进而延误进度。而swagger正好用来描述项目api，在后端定义，在前端可视化api，其前后端交互的契约为json格式的api信息. 详细的前后端api描述信息可参考Swagger RESTful API Documentation Specification
描述信息分两类，一类是resource listing，另一类是 api declaration. 前者是概要，描述一共有多少类的api信息，后者描述具体的每一个api定义.可参考Swagger RESTful API Documentation Specification

如何使用

本文基于spring-mvc，前提是api可被正常访问，在些基础上，我们增加swagger的api描述
首先加入引用

<dependency>·
   <groupId>com.mangofactory</groupId>
   <artifactId>swagger-springmvc</artifactId>
   <version>1.0.2</version>
</dependency>
<!--前面分析，还需要支持json序列化，如果项目中没有引入相关jackson或者fastjson的话，也同样需要引入.此处不给具体的依赖--> 

前端处理
从https://github.com/swagger-api/swagger-ui 从该处下载zip包。解压后，将dist文件夹下的所有内容copy到Java Web project的webapp下。可以新建一个目录，笔者建的目标为docapi，如图所示

修改index中的 url 地址，修改后的地址即为最后访问api信息的地址，要注意docapi里面的文件都可以正常被servlet访问

而url后面的 /api-docs ,是可以获取api协议的请求地址, 对于引用的com.mangofactory: swagger-springmvc:1.0.2 包来讲, 地址为 /api-docs,可参考后文的源码分析

此时前端已处理完成.
后端处理
在相应的controller中增加swagger 注解
demo 代码很简单，采用map进行存储用户，实现用户的增删改查操作

@Controller
@Api(value="/person"，description="针对用户的插入，删除，查看等操作")
@RequestMapping("/person")
public class TestController {
   
    private ConcurrentMap<Integer，Person> store = Maps.newConcurrentMap();
    private AtomicInteger atomicInteger = new AtomicInteger(0);

    @RequestMapping(value = "/show/{id}"，method= RequestMethod.GET)
    @ResponseBody
    @ApiOperation(value="查看"，notes="查看用户"， response = Person.class)
    public Person getPerson(@PathVariable("id")int id){
        Person person = store.get(id);
        return person == null ? null : person;
    }

    @RequestMapping(value =