Spring Boot集成Swagger导入YApi@无界编程

接口APi开发现状

现在开发接口都要在类似YApi上写文档，这样方便不同的团队之间协作，同步更新接口，提高效率。

但是如果接口很多，你一个个手工在YApi去录入无疑效率很低。

如果是使用Spring Boot集成Swagger可以直接导入YApi非常方便，不过还有一些需要注意的事项。

1.Spring Boot集成Swagger

添加swagger相关的maven依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

复制

2.添加swagger的配置类

@Configuration
@EnableSwagger2
@ComponentScan(basePackages = { "xxx.controller" })//扫描的包路径
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .paths(PathSelectors.any()).build();
    }

/**
     * 该套 API 说明，包含作者、简介、版本、host、服务URL
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("api 说明")//接口标题
                .description("商品列表接口")//接口描述
                .version("v1.0")//版本号
                .contact(new Contact("name", "url", "email"))//联系人信息
                .build();
    }
}

复制

或者

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("xxx.controller")) //扫描的包路径
                .build();
    }

    /**
     * 该套 API 说明，包含作者、简介、版本、host、服务URL
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("api 说明")
                .contact(new Contact("allen","null","[email protected]"))
                .version("0.1")
                .termsOfServiceUrl("localhost:8080/demo/")
                .description("demo api")
                .build();
    }

}

复制

3.使用Swagger注解

@Api()用于类；

标识这个类是swagger的资源

tags–表示分组说明标签

@ApiOperation()用于方法；

表示一个http请求的操作

value用于方法描述

notes用于提示内容

@ApiModel()用于实体类

表示对类进行说明，用于参数用实体类接收

value–表示对象名

description–描述

@ApiModelProperty()用于实体类字段

表示对model属性的说明或者数据操作更改

value–字段说明

name–重写属性名字

dataType–重写属性类型

required–是否必填

example–举例说明

hidden–隐藏

@ApiImplicitParam() 用于 controller 方法

表示单独的请求参数

name–参数ming

value–参数说明

dataType–数据类型

paramType–参数类型

example–举例说明

@ApiImplicitParams() 用于 controller 方法，包含多个 @ApiImplicitParam

@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上

说明：简单的标记只需要@Api(tags="") 和 @ApiOperation(value="",notes="")

更多参考：https://github.com/swagger-api/swagger-core/wiki/Annotations

4.Java代码写上Swagger注解

@Api(tags = "xxx查询列表Api")
@RestController
@RequestMapping(value = {"/xx/"}, produces = {MediaType.APPLICATION_JSON_VALUE})
public class xxxApiController {


    @GetMapping("/xxx/getAllList")
    */
    @ApiOperation("xxxx-查询列表")
    @PostMapping(value = {"/xxx/getList", "/front/getCount"}

复制

5.查看Swagger UI

随着你系统的URL路径不同而不同，默认在这

http://localhost:8080/swagger-ui.html

如果你有服务的前缀xxx-service加上即可

http://localhost:8080/xxx-service/swagger-ui.html

查看某一个controller下的接口列表：

查看某个具体接口：

返回值

至此swagger的任务已经完成。

6.swagger导入YApi

swagger ui显然看起来还是不方便，目前很多公司都在用YApi做接口的标准文档管理了。

YAPI里点数据管理，然后导入swagger的json数据即可。

注意这里YAPI号称支持导入swagger的URL，发现不好用，导入不进来。

回到swagger的UI界面

点这个链接，打开复制数据存为xxx.json即可，如果存txt也许会乱码

导入yapi即可

在Ypai里看起来是不是清爽很多：

本文由来源 21aspnet，由 system_mush 整理编辑，其版权均为 21aspnet 所有，文章内容系作者个人观点，不代表 Java架构师必看对观点赞同或支持。如需转载，请注明文章来源。