Swagger扫盲+springmvc集成Swagger

1.swagger 是什么？

swagger是一个让你自动生成接口文档的一个框架
直接上图：

image

2.为什么要用swagger？

从java后台来看，平时工作的时候是不是要给android，ios，前端，提供接口？是不是要写接口文档？是不是因为一些文档原因大吵一架？写文档是不是很痛苦？ 这个时候你就需要swagger了！

3.如何用swagger去整合springmvc？

本人项目用的是springmvc+spring+maybatis（ssm）框架，所以当然是用spring去整合了，当然也用maven管理项目模块

 spring版本 4.3.10.RELEASE
 jackson版本 2.9.5

3.1项目依赖

    
        com.google.guava
            guava
            20.0
    


    
        com.fasterxml.jackson.core
        jackson-annotations
        ${org.jackson-version}
    
    
        com.fasterxml.jackson.core
        jackson-databind
        ${org.jackson-version}
    
    
        com.fasterxml.jackson.core
        jackson-core
        ${org.jackson-version}
    
    
        com.fasterxml
        classmate
        1.1.0
    
            

      
          com.mangofactory
          swagger-springmvc
          1.0.2
      
      
          com.mangofactory
          swagger-models
          1.0.2
      
      
          com.wordnik
          swagger-annotations
          1.5.3-M1
      

3.2 Swagger配置

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;

/**
* @Description:swagger配置
* @Author: LKD
* @Date: 2018/08/07 16:37
*/
@Configuration
@EnableSwagger
@EnableWebMvc
public class SwaggerConfig {

   @Autowired
   private SpringSwaggerConfig springSwaggerConfig;


   public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
   {
       this.springSwaggerConfig = springSwaggerConfig;
   }

   @Bean
   public SwaggerSpringMvcPlugin customImplementation()
   {
       return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
               .apiInfo(apiInfo())
               .includePatterns(".*?");
   }

   private ApiInfo apiInfo()
   {
       ApiInfo apiInfo = new ApiInfo(
               "Beamtech接口文档",
               "功能接口一览",
               "",
               "[email protected]",
               "",
               "");
       return apiInfo;
   }
}

再你的springmvc的配置文件中声明 springSwaggerConfig

下面切入到实际方法中

/**
 * 根据用户名获取用户对象
 * @param name
 * @return
 */
@RequestMapping(value="/name/{name}", method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "根据用户名获取用户对象", httpMethod = "GET", response = ApiResult.class, notes = "根据用户名获取用户对象")
public ApiResult getUserByName(@ApiParam(required = true, name = "name", value = "用户名") @PathVariable String name) throws Exception{
    UcUser ucUser = ucUserManager.getUserByName(name);

    if(ucUser != null) {
        ApiResult result = new ApiResult();
        result.setCode(ResultCode.SUCCESS.getCode());
        result.setData(ucUser);
        return result;
    } else {
        throw new BusinessException("根据{name=" + name + "}获取不到UcUser对象");
    }
}
  上述代码是Controller中的一个方法，@ApiOperation注解对这个方法进行了说明，@ApiParam注解对方法参数进行了说明。关于这两个注解的使用，可以参看源码。这样子，Swagger就可以扫描接口方法，得到我们自定义的接口说明内容。

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

3.3使用swagger-ui

默认扫描得到一个json文档，给别人看不可能看json吧，这个时候需要使用一波swagger-ui美化一波
下载地址：https://github.com/swagger-api/swagger-ui
UI版本要求:【2.0-3.0之间版本】
存放位置:压缩包中,dist 目录下东西放到需要集成的项目里，我放在 src/main/webapp/WEB-INF/swagger/ 目录下

image.png

修改默认:swagger/index.html 默认是连接http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON，我们需要修改成自己的 url为: [http://{ip}:{port}/{projectName}/api-docs].这样写死，当项目名和ip地址变化的话会有弊端，可以使用在下封装的方法

 //获取文档路径
      function getDocUrl(){
          //获取当前网址，如： http://localhost:8080/Tmall/index.jsp
          var curWwwPath=window.document.location.href;
          //获取主机地址之后的目录如：/Tmall/index.jsp
          var pathName=window.document.location.pathname;
          var pos=curWwwPath.indexOf(pathName);
          //获取主机地址，如： http://localhost:8080
          var localhostPaht=curWwwPath.substring(0,pos);
          //获取带"/"的项目名，如：/Tmall
          var projectName=pathName.substring(0,pathName.substr(1).indexOf('/')+1);
          var docUrl =localhostPaht+projectName+"/api-docs";

          return docUrl;
      }

image.png

修改语言：默认是英文，换成中文，在上面的index.html中，打开注释，替换成中文

image.png

  ###3.3大功告成

打开浏览器输入
http://{ip}:{port}/{projectName}/swagger/index.html

image.png

image.png

image.png