Swageer学习文档

Swagger简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

按照现在的趋势，前后端分离几乎已经是业界对开发和部署方式所达成的一种共识。所谓的前后端分离，并不是传统行业中的按部门划分，一部分人只做前端（HTML/CSS/JavaScript等等），另一部分人只做后端（或者叫服务端），因为这种方式是不工作的：比如很多团队采取了后端的模板技术（JSP, FreeMarker, ERB等等），前端的开发和调试需要一个后台Web容器的支持，从而无法将前后端开发和部署做到真正的分离。归根结底，还是前端或者后端感知到变化的时间周期太长，不能“及时协商，尽早解决”，最终导致集中爆发。怎么解决这个问题呢？Swagger将是一个很好的帮助我们更好的实现“前后端分离”的框架。

 

2.Swagger是一组开源项目，其中主要项目如下：

 

1. Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

2. Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。

3. Swagger-js: 用于JavaScript的Swagger实现。

4. Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。

5. Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。

6. Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

7. Swagger-editor：可让使用者在浏览器里以YAML格式编辑Swagger API规范并实时预览文档。可以生成有效的Swagger JSON描述，并用于所有Swagger工具（代码生成、文档等等）中。

除了Swagger项目自身支持的Java、Scala和JavaScript语言，Swagger社区中还提供了很多支持其他语言的第三方工具，覆盖了Clojure、ColdFusion / CFML、Eiffel、Go、Groovy、.Net、Perl、PHP、Python、Ruby等各种编程语言。

 

3.Swagger 与 SpringMVC的项目整合

3.1 在项目中引入相关jar包：

3.2 添加自定义config文件：

package com.spg.apidoc.common.configer;

 

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

 

import com.mangofactory.swagger.configuration.SpringSwaggerConfig;

import com.mangofactory.swagger.models.dto.ApiInfo;

import com.mangofactory.swagger.plugin.EnableSwagger;

import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;

 

/**

 * 项目名称：apidoc

 *

 * @description:

 * @author Wind-spg

 * @create_time：2015年2月10日 上午10:27:51

 * @version V1.0.0

 *

 */

@Configuration

@EnableSwagger

// Loads the spring beans required by the framework

public class MySwaggerConfig{

 

    private SpringSwaggerConfig springSwaggerConfig;

 

    /**

     * Required to autowire SpringSwaggerConfig

     */

    @Autowired

    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig){

        this.springSwaggerConfig = springSwaggerConfig;

    }

 

    /**

     * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc

     * framework - allowing for multiple swagger groups i.e. same code base

     * multiple swagger resource listings.

     */

    @Bean

    public SwaggerSpringMvcPlugin customImplementation()

    {

        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig).apiInfo(apiInfo()).includePatterns(

                .*?);

    }

 

    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;

    }

}

 

3.3 将此配置加入到Spring容器中，如下：

3.4 在代码中添加相关APIAnnotation，如下：

     @ResponseBody

    @RequestMapping(value = addUser, method = RequestMethod.POST, produces = application/json; charset=utf-8)

    @ApiOperation(value = 添加用户, httpMethod = POST, response = BaseResultVo.class, notes = add user)

    public String addUser(@ApiParam(required = true, name = postData, value = 用户信息json数据) @RequestParam(

            value = postData) String postData, HttpServletRequest request){

        LOGGER.debug(String.format(at function, %s, postData));

        if (null == postData || postData.isEmpty())

        {

            return super.buildFailedResultInfo(-1, post data is empty!);

        }

 

        UserInfo user = JSON.parseObject(postData, UserInfo.class);

        int result = userService.addUser(user);

        return buildSuccessResultInfo(result);

    }

 

说明：
其中@ApiOperation和@ApiParam为添加的API相关注解，个参数说明如下：
@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”；其他参数可参考源码；
@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”

3.5 在GitHub上下载SwaggerUI项目，将dist下所有内容拷贝到本地项目webapp下面

3.6 修改index.html

将index.html中http://petstore.swagger.wordnik.com/v2/swagger.json修改为http://localhost:8080/{projectname}/api-docs

到此为止，所有配置完成，启动你的项目，访问http://localhost:8080/{projectName}/index.html即可看到效果。