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项目依赖

<!-- guava -->
    <dependency>
        <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>20.0</version>
    </dependency>
<!--jackson-->
<!--<org.jackson-version>2.9.5</org.jackson-version>-->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-annotations</artifactId>
        <version>${org.jackson-version}</version>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>${org.jackson-version}</version>
    </dependency>
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-core</artifactId>
        <version>${org.jackson-version}</version>
    </dependency>
    <dependency>
        <groupId>com.fasterxml</groupId>
        <artifactId>classmate</artifactId>
        <version>1.1.0</version>
    </dependency>
            
<!-- swagger-springmvc -->
      <dependency>
          <groupId>com.mangofactory</groupId>
          <artifactId>swagger-springmvc</artifactId>
          <version>1.0.2</version>
      </dependency>
      <dependency>
          <groupId>com.mangofactory</groupId>
          <artifactId>swagger-models</artifactId>
          <version>1.0.2</version>
      </dependency>
      <dependency>
          <groupId>com.wordnik</groupId>
          <artifactId>swagger-annotations</artifactId>
          <version>1.5.3-M1</version>
      </dependency>

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接口文档",
               "功能接口一览",
               "",
               "damonli0724@Gmail.com",
               "",
               "");
       return apiInfo;
   }
}

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

<!--注入SpringSwaggerConfig-->
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
<!--swagger 接口文档静态资源-->
<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>

下面切入到实际方法中

/**
 * 根据用户名获取用户对象
 * @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<UcUser> result = new ApiResult<UcUser>();
        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

<!-- Some basic translations -->
    <script src='lang/translator.js' type='text/javascript'></script>
  <!-- <script src='lang/ru.js' type='text/javascript'></script> -->
   <script src='lang/zh-cn.js' type='text/javascript'></script>