1.简介

Swagger是一个简单又强大的能为你的Restful风格的Api生成文档工具，可以自动生成页面形式的Api文档，并且提供测试的功能，Swagger使用起来方便、快捷、降低前后端以及测试的成本，有十分风骚且美观的界面供测试和查看。

2.缺点

Swagger嵌入在代码中，依赖强，容易污染代码，大型项目作用性不强（注解太多）若中途使用swagger成本较高。

3.上代码，聊人生

声明：本文章采用spring+spring mvc+swagger框架，数据方面模拟，其他多余东西没有。

3.1 创建Maven项目-导入依赖

[plain]view plain copy
<!-- swagger-mvc -->com.mangofactoryswagger-springmvc1.0.2<!-- swagger-mvc -->javax.servletjavax.servlet-api3.1.0providedjavax.servletjstl1.2com.fasterxml.jackson.corejackson-databind2.6.6org.springframeworkspring-webmvc4.1.6.RELEASEorg.springframeworkspring-web4.1.6.RELEASEorg.springframeworkspring-tx4.1.6.RELEASEorg.springframeworkspring-jdbc4.1.6.RELEASEorg.springframeworkspring-context4.1.6.RELEASEorg.springframeworkspring-context-support4.1.6.RELEASEorg.springframeworkspring-orm4.1.6.RELEASEorg.springframeworkspring-aop4.1.6.RELEASEorg.springframeworkspring-oxm4.1.6.RELEASEorg.springframeworkspring-test4.1.6.RELEASEtest<!-- slfj4 -->org.slf4jslf4j-log4j121.7.7<!-- slfj4 -->  

3.2 配置spring+spring mvc

[plain]view plain copy
<!-- 扫描注解Bean -->  

3.2 配置web.xml

[plain]view plain copy
contextConfigLocation  
         classpath:spring-config.xml  
     org.springframework.web.context.ContextLoaderListenerspringmvcorg.springframework.web.servlet.DispatcherServletcontextConfigLocationclasspath:spring-mvc.xml1springmvc/  

3.3 Swagger配置信息

[java]view plain copy
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.DefaultServletHandlerConfigurer;  
import org.springframework.web.servlet.config.annotation.EnableWebMvc;  
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;  
  
import com.mangofactory.swagger.configuration.SpringSwaggerConfig;  
import com.mangofactory.swagger.models.dto.ApiInfo;  
import com.mangofactory.swagger.paths.SwaggerPathProvider;  
import com.mangofactory.swagger.plugin.EnableSwagger;  
import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;  
  
@Configuration  
@EnableWebMvc  
@EnableSwagger  
public class SwaggerPluginConfig extends WebMvcConfigurerAdapter {  
  
    private SpringSwaggerConfig springSwaggerConfig;  
  
    @Bean  
    public SwaggerSpringMvcPlugin customImplementation() {  
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)  
                .apiInfo(apiInfo())  
                .includePatterns(".*")  
                .useDefaultResponseMessages(false)  
                // .pathProvider(new GtPaths())  
                .apiVersion("0.1")  
                .swaggerGroup("user");  
  
    }  
  
    private ApiInfo apiInfo() {  
        ApiInfo apiInfo = new ApiInfo("这是标题-Laher", "这是描述-Laher",  
                "服务条款路径", "[email protected]", "Laher博客",  
                "http://blog.****.net/weisheixiaoxin");  
        return apiInfo;  
    }  
  
    @Override  
    public void configureDefaultServletHandling(  
            DefaultServletHandlerConfigurer configurer) {  
        configurer.enable();  
    }  
  
    class GtPaths extends SwaggerPathProvider {  
        @Override  
        protected String applicationPath() {  
            return "/restapi";  
        }  
  
        @Override  
        protected String getDocumentationPath() {  
            return "/restapi";  
        }  
    }  
  
    @Autowired  
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {  
        this.springSwaggerConfig = springSwaggerConfig;  
    }  
}  

3.4 Controller中使用注释声明节点

[java]view plain copy
//swagger的节点声明，节点名称，类型。  
@Api(value = "user", description = "用户管理", produces = MediaType.APPLICATION_JSON_VALUE)  
@Controller  
@RequestMapping("user")  
public class UserController  

3.5 接口方法注释声明

[java]view plain copy
//swagger的节点声明，节点名称，类型。  
@ApiOperation(value = "查询用户", notes = "查询用户信息", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_VALUE)  
//spring mvc注解声明  
@ResponseBody  
@RequestMapping(value = "get", method = RequestMethod.GET)  
//                          -swagger声明入参变量的英文和是否空         -spring mvc入参声明 这个一定要加  
public Result get(@ApiParam(value = "编号", required = true) @RequestParam String id) {  
    return new Result(0000, "操作成功", getUser(id));  
}  