API接口在线管理（Swagger和SosoApi）

1.Swagger
1.1. Swagger介绍
1.1.1. 简介
Swagger是全球最大的API开发框架，这个框架以“开放API声明（OpenAPI Specification,OSA）”为基础，支持整个API生命周期的开发。它可以和SpringMVC整合，并且通过结合Swagger-ui组件，将controller层的方法进行可视化的展示，像方法注释，方法参数，方法返回值等都提供了相应的用户界面。用户可以在该界面对每个接口进行测试。
OSA，本身是一个规范，它是一个描述一整套API接口的json文件，包括接口的请求方式，参数，header等等信息。

1.1.2. 为什么使用Swagger?
在工作中，如果开发人员遇到写接口文档的工作，一般都是word文档，带来书写麻烦，维护麻烦的问题，比如改了源代码忘了更新文档，解释不明确带来歧义，无法在线尝试等等。而Swagger封装了在线自动生成接口文档及进行功能测试的功能,正好可以解决这种问题。

1.1.3. 优缺点
优点：
 在线生成API文档并测试，易维护；
 可以和多种不同框架整合（除了SpringMVC，还有struts2，jersey2，cxf等等），应用范围广；
 测试的时候不需要再使用浏览器输入URL的方式来访问Controller，使用简单方便，学习成本低。

缺点：
 没有导出的功能，文档只能在线看及在线测试，不能导出到本地（这也是后面讲SosoApi的原因）。
1.1.4. 用法比较
Swagger的使用有很多方式，这里选取3种比较常用的使用方式来进行比较:
这里写图片描述

Springfox是从组件swagger-springmvc发展而来，是一个新的项目，部署的时候，使用的是其中一个组件springfox-swagger2,该组件帮助我们生成描述API的json文件。
上面用法各有优缺点，可按实际情况来选。大体上来说，Swagger4j和Springfox+Swagger2都在jar包中整合了Swagger UI组件，配置相对简单。Springfox+Swagger2是Swagger的升级版本。
1.2. 本地部署
鉴于笔者所用框架为ssm，笔者在这里只介绍Swagger整合SpringMVC进行本地部署。
1.2.1. Swagger部署
新建一个web maven 项目SwaggerProject，搭建好Spring+SpringMVC+MyBatis框架；
1.2.1.1. 添加依赖
在SwaggerProject中添加如下依赖：

<dependency>
    <groupId>com.mangofactory</groupId>
    <artifactId>swagger-springmvc</artifactId>
    <version>0.9.5</version>
</dependency>

1.2.1.2. 添加配置类
添加一个Swagger配置类，并在spring-mvc.xml文件配置扫描这个类。

@Configuration
@EnableSwagger // 启用Swagger
public class MySwaggerConfig {
    private SpringSwaggerConfig springSwaggerConfig;
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
        this.springSwaggerConfig = springSwaggerConfig;
    }
    @Bean
    public SwaggerSpringMvcPlugin customImplementation() {
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo());
    }
    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                  "My Apps API Title",
                  "My Apps API Description",
                  "My Apps API terms of service",
                  "My Apps API Contact Email",
                  "My Apps API Licence Type",
                  "My Apps API License URL"
            );
        return apiInfo;
    }
}

1.2.1.3. 配置web.xml
在web.xml中进行如下配置，以启动Servlet默认加载机制，确保SwaggerUI这些文件不会被拦截。

<servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.jpg</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.png</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.gif</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.ico</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.js</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.css</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.html</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.xls</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.doc</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.json</url-pattern>
    </servlet-mapping>
    <!-- 字体相关  开始 -->
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.eot</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.svg</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.ttf</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.woff</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>default</servlet-name>
        <url-pattern>*.woff2</url-pattern>
    </servlet-mapping>

1.2.1.4. 加入Swagger UI组件。
在github上下载Swagger UI组件，地址为：https://github.com/swagger-api/swagger-ui。解压后将dist目录下所有文件拷贝到项目的webapp目录下，并且修改index.html文件中url为自己的“项目路径/api-docs”。
1.2.1.5. 修改controller
先了解Swagger的几个常用注解：
 @Api：表示这个类是Swagger的资源；
 @ApiOperation：用在方法上，说明方法的作用。
 @ApiParam：用来修饰参数，表示对参数添加元数据
 @ApiModel：用于类，对类进行说明
 @ApiIgnore：用于类，方法，表示这个类或方法被忽略；
 @ApilmplicitParam：用于方法，表示单独的请求参数；
修改后的controller及方法一般形式如下：

@Api(value = "/user", description = "关于用户的一些操做")
@Controller
public class UserController {
    @ResponseBody
    @RequestMapping(value = "getUserById", method = RequestMethod.GET)
    @ApiOperation(value = "通过ID查询USER信息", httpMethod = "GET", notes = "暂无")
    public String getUserById(
            @ApiParam(required = true, name = "id", value = "ID") 
            @RequestParam(value = "id") int id,HttpServletRequest request) {
        User user = new User();
        user.setId(id);
        user.setName("测试人员");
        user.setAge(25);
        JSONObject object = JSONObject.fromObject(user);
        return object.toString();
    }
}

这些注解并不一定都要用到，实际上，由于Spring已经提供了一套完整的注解方式，这些Swagger的注解起的只是锦上添花的作用。在结合我们项目进行测试的过程中，为了使代码的改动最小，我并没有使用这些注释，而是保持原有代码不变，然后为原来的@RequestMapping注解添加请求方式，并根据请求参数类型给请求参数添加@RequestParam或@RequestBody注解。
1.2.1.6. 启动并测试
将项目添加到tomcat，并启动tomcat，正常会出现如下界面：
这里写图片描述

点击列表上面的“Expand Operations”选项，可以弹出如下界面：
这里写图片描述
在这里，可以对每个接口进行测试。

1.2.2. Swagger4j部署
1.2.2.1. 添加依赖

<dependency>
    <groupId>com.cpjit</groupId>
    <artifactId>swagger4j</artifactId>
    <version>2.1.1</version>
</dependency>

1.2.2.2. 修改spring-mvc.xml
在spring-mvc.xml文件中添加如下代码以加载jar包中的Swagger UI组件：

    <mvc:resources mapping="/**/*.css" location="/" />
    <mvc:resources mapping="/**/*.js" location="/" />
    <mvc:resources mapping="/**/*.png" location="/" />
    <mvc:resources mapping="/**/*.gif" location="/" />
    <mvc:resources mapping="/**/*.jpg" location="/" />
    <mvc:resources mapping="/**/*.ico" location="/" />
    <mvc:resources mapping="/**/*.woff" location="/" />
    <mvc:resources mapping="/**/*.woff2" location="/" />
    <mvc:resources mapping="/**/*.fft" location="/" />
    <mvc:resources mapping="/**/*.svg" location="/" />
    <mvc:resources mapping="/**/*.eot" location="/" />
    <mvc:resources mapping="/**/*.html" location="/" />
    <mvc:resources mapping="/**/*.mp3" location="/" />

1.2.2.3. 添加配置文件
新建配置文件swagger.properties（这个名称是唯一的），注意第一项要扫描的包路径要改成自己项目的需要扫描的路径。

packageToScan=com.cpjit.swagger4j.demo
apiDescription=Swagger Demo
apiTitle=Swagger Demo
apiVersion=1.0.0
teamOfService=www.cpj.com
devMode=true
disabled=false

1.2.2.4. 修改controller
首先了解几个重要的注解：
@APIs：该注解放在一个类上面，用来表明类中包含作为HTTP接口的方法，该注解的value用来设置接口的前缀；
@API：该注解放在一个方法上面，用来表明方法是HTTP接口方法，注解的属性说明如下：
 value：与@APIs的value属性一起来指定接口的地址。
 parameters：用来指定接口的请求参数；
 summary：接口功能简述；
 description：接口功能详细说明；
 method：请求方式，默认是post。
@Param：用来说明请求参数。
Controller层的类和方法的形式大致如下：

@Controller
@RequestMapping("/demo")
@APIs("/demo")
public class DemoController {
    @API(value="login", summary="示例1", parameters={
            @Param(name="username", description="用户名", dataType=DataType.STRING, defaultValue = "admin"),
            @Param(name="password", description="密码", dataType=DataType.PASSWORD),
            @Param(name = "sex", description = "性别", dataType = DataType.ARRAY, items = "sex"),
            @Param(name = "age", description = "年龄", dataType = DataType.INTEGER, defaultValue = "18"),
            @Param(name="image" , description="图片", dataType=DataType.FILE)
    })
    @RequestMapping(value="login", method=RequestMethod.POST)
    public void login(@RequestParam Map<String, Object> param, MultipartFile image, HttpServletResponse response) throws Exception {
        response.setContentType("application/json;charset=utf-8");
        JSONWriter writer = new JSONWriter(response.getWriter());
        writer.writeObject(param);
        writer.flush();
        writer.close();
    }

1.2.2.5. 启动并测试
访问http://localhost:8083/swagger-demo-springmvc/api，可得到api的完整json数据：
这里写图片描述

访问http://localhost:8083/swagger-demo-springmvc/api/index，可得到如下页面，效果和Swagger并无二致。
这里写图片描述
点击路径展开具体接口信息：

1.2.3. Springfox+Swagger2部署
1.2.3.1. 添加依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.5.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.5.0</version>
        </dependency>

1.2.3.2. 修改spring-mvc.xml文件

<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html" />
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**" />

1.2.3.3. 添加配置文件
新建SwaggerConfig.java文件，添加如下代码：

@Configuration
@EnableWebMvc // 支持springmvc
@EnableSwagger2 // 启用Swagger2
@Component
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
            .apis(RequestHandlerSelectors.basePackage("com.chen.controller"))
            // 扫描所有有注解的api
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("RESTful APIs").description("Spring+MVC集合Swagger2的API")
            .termsOfServiceUrl("http://localhost:8080").version("1.0.0").build();
    }
}

1.2.3.4. 修改controller
各个注解和Swagger部署中的意思是一样的。Controller层的方法一般形式如下：

@Api(value = "UserInfoController", description = "UserInfoController", position = 1)
@Controller
@RequestMapping("/UserInfoController")
public class UserInfoController {

    @ResponseBody
    @ApiOperation(value = "查询用户", notes = "返回用户实体对象", position = 1)
    @RequestMapping(value = "/query", method= RequestMethod.POST)
    public UserInfo query(@RequestParam(value="id")Long id){
        UserInfo userInfo = new UserInfo();
        userInfo.setId(id);
        userInfo.setName("张三");
        userInfo.setAddress("广州");
        return userInfo;
    }
}

1.2.3.5. 启动并测试
启动项目，访问路径：http://localhost:8082/information/v2/api-docs，可得到api的完整json数据：
这里写图片描述

访问路径：http://localhost:8082/information/swagger-ui.html#/，可得到如下界面：
这里写图片描述

点击右上角“Expand Operations”，出现如下界面，这时候就可以测试了。
这里写图片描述

它主要是通过EnableSwagger2注解，向srping context注入了一系列bean，并在系统启动的时候自动扫描系统的Controller类，生成相应的api信息并缓存起来。此外，它还注入了一些被@Controller注解标识的Controller类，作为ui模块访问api列表的入口。

1.2.4. 原理分析
SpringMVC+Swagger自动生成在线api文档，其实就是在系统加载的时候，Swagger配置类去扫描所有添加注解的接口，并且储存起来生成完整的json文件，然后使用Swagger-UI组件，将这个json文件解析出来，用一种更友好的方式呈现出来。

1.2.5. 参考资料
鉴于Swagger的部署流程比较简单，测试也比较简单，网上很多资料也介绍的很详细，这里选取介绍的比较详细的几篇：
Swagger：http://blog.csdn.net/u011499992/article/details/53455144；
Swagger4j：https://github.com/cpjit/swagger；
Springfox+Swagger2：http://blog.csdn.net/he90227/article/details/52119506，
https://www.cnblogs.com/getupmorning/p/7267076.html。

2.SosoApi
2.1. 简介
是一个专注于API接口文档管理及线上线下测试的API服务平台。

2.2. 特点
 提供丰富的在线文档，包括线上编辑和线下部署及常见问题，减少上手学习成本。
 通过编辑表单的方式创建基于swagger ui的数据文档，从而可在线预览和测试。
 解决了swagger editor学习成本高及代码集成不好维护的问题。
 为方便小团队及公司内部使用，可导出swagger数据文档线下部署。
 不会对已有项目产生任何代码入侵。

2.3. 使用
2.3.1. 在线使用
登录http://www.sosoapi.com官网使用，上面有详细的指导手册，大家一看就明白了。这里主要补充一点：sosoapi去年还没有添加“导入”的功能，今年增加了，但只有在线的版本有导入功能，开源版本没有，所以笔者推荐使用在线版本以节省人力。有了导入功能，那么只要导入接口的json文件就可以自动生成接口文档了（刚好swagger可以生成json文件），我们只要输入必要的参数就可以进行测试了。

2.3.2. 本地部署
到https://github.com/sosoapi这个地址下载SosoApi的开源版本，
这里写图片描述

下载sosoapi-web 和 framework 项目，导入eclipse。然后再用maven构建一下。注意，sosoapi-web 依赖 frameWork项目。
然后根据db目录下的sosoapi.sql文件，创建数据库并执行sql脚本，修改与数据库相关的各个配置文件。
本地运行该项目，端口号为8080，若一切正常，访问http://localhost:8080/sosoapi-web会出现如下界面：
这里写图片描述

之后的操作和线上使用的方式是一样一样的。

对比Swagger与SosoApi
下面是Swagger与SosoApi的一些比较：

之所以把Swagger和SosoApi放在一起讲，是因为笔者暂时没有找到既可以自动生成API文档，又能导出文档的方法。这两种各有其作用，根据需求及专注的重点，选择其中一种或两者皆选。就笔者认为，若项目不要求提供线下的API文档或不要求对Api进行整体管理，应当选择Swagger（或者啥都不选，写测试用例也很好）。反之则同时使用Swagger和SosoApi，使用Swagger生成json文件，然后将json文件导入sosoapi，就可以得到接口文档及可导出多种格式的接口文档。

API接口在线管理（Swagger和SosoApi）

猜你喜欢