swagger使用笔记

java
阅读次数:次

1. 关于swagger

是一个接口测试框架，用于生成接口文档，暂时接口页面，可以直接在页面进行执行接口，黑盒测试接口的情况！

官网： https://swagger.io/

swagger利用spring-fox将其与spring整合在一起，让我们先来理一理springfox与swagger的关系：

  • swagger是一个六星的API开发框架，这个框架以“开放API声明”（OpenAPI Specification , OAS）为基础，对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）
  • OAS本身是一个API规范，它用于描述一整套API接口，包括一个接口是GET还是POST请求啊，有哪些参数哪些header啊，都会被包括在这个文件中。它在设计的时候通常是YAML格式，这种格式书写起来比较方便，而在网络中传输时又会以json形式居多，因为json的通用性比较强。
  • 由于Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来。而springfox则是从这个组件发展而来，同时springfox也是一个新的项目，本文仍然是使用其中的一个组件springfox-swagger2。
  • pringfox-swagger2依然是依赖OSA规范文档，也就是一个描述API的json文件，而这个组件的功能就是帮助我们自动生成这个json文件，我们会用到的另外一个组件springfox-swagger-ui就是将这个json文件解析出来，用一种更友好的方式呈现出来。

2.实例

2.1 maven依赖

 <properties>
    <springfoxversion>2.4.0</springfoxversion>
</properties>
<dependencies>
     <!-- swagger2 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${springfoxversion}</version>
    </dependency>
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${springfoxversion}</version>
    </dependency>
</dependencies>

说明： 第一个类库是用于生成api-docs ，返回关于controller接口的的json格式数据。

2.2 swagger配置

@EnableSwagger2
@EnableWebMvc
@ComponentScan(basePackages = {"com.**.**.web.controller"})
public class Swagger2Config{
    @Bean
    public Docket customDocket() {

        return new Docket(DocumentationType.SWAGGER_2)
                .select()            //select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现
                .apis(RequestHandlerSelectors.any()) 
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        Contact contact = new Contact("wwl", "", "");
        return new ApiInfo("**API接口",        // 标题
                "** API接口，仅用于测试环境",    // 小标题
                "1.0.0",                    // 版本
                "http://www.baidu.com/",    // 服务网址
                contact,                    // 作者
                "Apache 7.0",                // license
                "http://www.apache.org/licenses/LICENSE-2.0"  // license url
        );
    }
}

这样的配置是没有注入到Spring中的，可以用注解方式如下：

@Configuration

但是注解的话，不好控制swagger的开关，因为swagger一般只用于在测试阶段。所以可以使用spring配置方式如下：

<!-- Enables swgger ui -->
<bean class="com.sj.test.swagger.Swagger2Config" />

在生产阶段的时候，直接去掉这一段即可。

另外， 由于用的是注解方式，所以还需要开启spring注解如下：

<mvc:default-servlet-handler />

完成以上步骤以后，直接运行后，访问： http://localhost:8080/swagger-ui.html ,结果如下：

点开每一个方法后，可以自行注入参数，并点击 【Try it out!】开始测试，并在下方显示返回结果【json 或者 html数据】

访问：http://localhost:8080/v2/api-docs 可以查看接口的json格式数据。

2.3Controller注解接口说明

其实以上完成以后，接口测试界面已经出来，但是生成的接口文档阅读性不好，所以可以再controller文件，利用注解的方式添加接口说明。

@Api(value = "对外接口管理", description = "对外接口管理")
@Controller
@RequestMapping("service")
@SuppressWarnings({ "unchecked", "rawtypes" })
public class ExternalController {

    @ApiOperation(value = "获取服务地址")
    @RequestMapping("getserveraddress")
    @ResponseBody
    public ResultInfo<GlobalConfig> getserveraddress(@RequestParam("portalID")String portalID){

        ResultInfo<GlobalConfig> info = new ResultInfo<GlobalConfig>();

        try{
            // ...省略处理过程

            info.setErrorCode(0);
            info.setResult(result);
            return info;

        } catch (Exception e){
            logger.error(e.getMessage(), e.fillInStackTrace());
        }

        return ResultInfo.getIllegalDataAccess();
    }
}

说明：在controller类上添加以下注解，是对Controller类的说明

@Api(value = "对外接口管理", description = "对外接口管理")

在接口方法上添加以下注解，是对接口的说明

@ApiOperation(value = "获取服务地址")

添加完成以后，可以看到结果如下：

本站总访问量次