文章目录

  1. 1. 我们遇到的问题
  2. 2. Swagger的好处
  3. 3. Swagger的整合
    1. 3.1. 依赖管理
    2. 3.2. Swagger配置
    3. 3.3. 配置注解
    4. 3.4. Swagger-UI配置
    5. 3.5. 访问

我们遇到的问题

在开发我们的系统时,前端基于reactJS框架,和后端完全解耦,所有的交互都是通过REST Service完成,同时后端各个领域系统间也是通过REST Service来通信。REST本身虽然有统一的规范,然而对于REST API的管理却没有统一规范,再加上前期时间紧迫,没有足够的资源去做详细的文档说明。API定义的沟通就只能依赖UI和后台开发人员的口头沟通。

Swagger的好处

Swagger是为了描述一套标准的而且是和语言无关的REST API的规范。对于外部调用者来说,只需通过Swagger文档即可清楚Server端提供的服务,而不需去阅读源码或接口文档说明。

Swagger的整合

依赖管理

<!-- 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.3.11</version>
</dependency>
<!-- swagger-springmvc dependencies -->
<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>
<dependency>
    <groupId>com.fasterxml</groupId>
    <artifactId>classmate</artifactId>
    <version>1.1.0</version>
</dependency>

Swagger配置

我们通过Java Config的方式来配置Bean。

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;

@Configuration
@EnableSwagger
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(
                "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;
    }
}

配置注解

/**
 * 根据用户名获取用户对象
 * @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对象");
    }
}

Swagger-UI配置

https://github.com/swagger-api/swagger-ui 获取其所有的 dist 目录下东西放到需要集成的项目里,本文放入 src/main/webapp/swagger/ 目录下。

修改swagger/index.html文件,默认是从连接http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON,这里需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式,{}中的值根据自身情况填写。比如我的url值为:http://localhost:8083/arrow-api/api-docs

因为swagger-ui项目都是静态资源,restful形式的拦截方法会将静态资源进行拦截处理,所以在springmvc配置文件中需要配置对静态文件的处理方式。

//所有swagger目录的访问,直接访问location指定的目录
<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>

访问

运行项目,通过http://{ip}:{port}/{projectName}/swagger/index.html访问 。

(完)

微信公众号

文章目录

  1. 1. 我们遇到的问题
  2. 2. Swagger的好处
  3. 3. Swagger的整合
    1. 3.1. 依赖管理
    2. 3.2. Swagger配置
    3. 3.3. 配置注解
    4. 3.4. Swagger-UI配置
    5. 3.5. 访问