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","name@example.com"))
                .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里看起来是不是清爽很多:

©️2020 CSDN 皮肤主题: 深蓝海洋 设计师: CSDN官方博客 返回首页
实付0元
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值