使用swagger2自动生成RESTful接口文档导入yapi

背景

项目使用springmvc进行设计，接口手动录入yapi比较繁琐；

查找资料通过swagger可以导入Postman及yapi；

所以决定试一下通过swagger2进行接口文档自动生成并导入yapi。

具体操作

步骤1：在pom.xml文件中添加如下依赖

    io.springfox

    springfox-swagger2

    ${swagger.version}

    io.springfox

    springfox-swagger-ui

    ${swagger.version}

其中${swagger.version}取值为2.2.2

步骤2.1：创建SwaggerConfig类，继承自WebMvcConfigurerAdapter，并添加注解：

@Configuration

@EnableSwagger2

步骤2.2：创建Docket，通过其select返回的ApiSelectorBuilder下的apis方法，设置具体的接口文档生成方式，覆盖如下两种：

方式1：只生成特定接口描述，通过在API对应的方法上面添加注解@ApiOperation给API增加说明，通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明

方式2：特定包下所有接口描述，通过指定包名，添加在该包下所有controller层下API说明，统一使用默认的说明方式生成文档；如果需要修改相关描述，可以使用@ApiOperation等注解进行说明

综合步骤2的具体代码如下（未贴出import相关代码）：

@Configuration

@EnableSwagger2

public class SwaggerConfig extends WebMvcConfigurerAdapter {

    @Override

    public void addResourceHandlers(ResourceHandlerRegistry registry) {

        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");

        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

    }

    @Bean

    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)

            .apiInfo(apiInfo())

            .select()

   .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))  //加了ApiOperation注解的方法，生成接口文档      //.apis(RequestHandlerSelectors.basePackage("io.renren.modules.job.controller"))  //包下的类，生成接口文档

            .paths(PathSelectors.any())

            .build();

    }

    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()

            .title("标题")

            .description("文档描述")

            .termsOfServiceUrl("服务条款对应的url")

            .version("1.3")

            .build();

    }

}

步骤3：编译并启动项目，通过http://ip:port/swagger-ui.html进行查看，同时可以输入接口参数，手动执行简单的测试；

步骤4：进入yapi的数据管理页面，通过swagger方式，输入swagger的json文件对应的url：http://{ip}:{port}/{project Name}/v2/api-docs 执行数据导入操作，如：http://127.0.0.1:8080/renren-fast/v2/api-docs

备注

关于yapi搭建，参见文章《docker-compose的方式搭建yapi》