什么是Swagger?

　　大部分 Web 应用程序都支持 RESTful API，但不同于 SOAP API——REST API 依赖于 HTTP 方法，缺少与 Web 服务描述语言（Web Services Description Language，WSDL）类似的语言来定义使用者与提供者之间的请求和响应结构。由于没有充分的合同服务，许多 REST API 提供者使用 Microsoft Word 文档或维基页面来记录 API 用法。这些格式使协作和文档版本控制变得很困难，尤其对于有许多 API 或资源的应用程序，或者在 API 采用迭代式开发方式时。这些文档类型在集成到自动化测试应用程序中时变得更难。

　　Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。

　　开源Swagger框架帮助 API 使用者和开发人员纠正了这些问题。该框架为创建 JSON 或 YAML（JSON 的一个人性化的超集）格式的 RESTful API 文档提供了Open API（以前称为 Swagger 规范）。Swagger 文档可由各种编程语言处理，可在软件开发周期中签入源代码控制系统中，以便进行版本管理。

　　一句话，Swagger是一个让我们可以更方便、更好的设计和表达api的一个开源框架。

　　Ps:

什么是openapi?

在互联网时代，把网站的服务封装成一系列计算机易识别的数据接口开放出去，供第三方开发者使用，这种行为就叫做开放网站的API，与之对应的，所开放的API就被称作openAPI。

如何使用Swagger：

　　本文，主要介绍Swagger和Spring MVC的集成使用(采用Maven管理jar包)，若您恰有此需求，请继续阅读。

　　首先，我们在pom.xml文件中添加如下：

<dependency>

           <groupId>com.mangofactory</groupId>

           <artifactId>swagger-springmvc</artifactId>

           <version>1.0.2</version>

       </dependency>

       <dependency>

           <groupId>com.google.guava</groupId>

           <artifactId>guava</artifactId>

           <version>15.0</version>

       </dependency>

       <dependency>

           <groupId>com.fasterxml.jackson.core</groupId>

           <artifactId>jackson-annotations</artifactId>

           <version>2.4.4</version>

       </dependency>

       <dependency>

           <groupId>com.fasterxml.jackson.core</groupId>

           <artifactId>jackson-databind</artifactId>

           <version>2.4.4</version>

       </dependency>

       <dependency>

           <groupId>com.fasterxml.jackson.core</groupId>

           <artifactId>jackson-core</artifactId>

           <version>2.4.4</version>

       </dependency>

由于Swagger获取api后是以json形式返回数据给Swagger ui，所以这里需要引入jackson的相关包

　　然后，建包config，在包下新建配置类SwaggerConfig，如图：

Spring MVC集成Swagger

　　代码如下，可自行copy更改：

package com.xykj.blog.config;

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;

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

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import org.springframework.web.servlet.config.annotation.EnableWebMvc;

@Configuration

@EnableSwagger

@EnableWebMvc

public class SwaggerConfig {

    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(

                "Swagger测试",

                "测试查询用户",

                "开发者: Changxin L",

                "348686686@gmail.com",

                "MIT License",

                "/LICENSE");

        return apiInfo;

    }

}