Swagger使用简介

在之前开发时,每次前端开发人员总是说:“后端的数据怎么老是增加呀,而且我要的数据没了”
我说:“1.产品那边改业务,接口改好后我通知到你了。2.要不下次做一个及时文档”

Swagger
  1. swagger是什么?
  2. 为什么使用swagger?
  3. 如何搭建一个swagger?
  4. 在项目中如何集成swagger?
  5. 是那个用swagger需要注意的问题
  6. 总结
Swagger 是什么?

Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化RESTFUL风格的web服务。目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法,参数和模型紧密集成到服务器。这个解释简单点来讲就是说,swagger是一款可以根据restful风格生成的接口文档,并且支持做测试的一款中间软件。

为什么使用swagger

1.对于后端开发人员来说

  • 不用再手写Wiki接口拼大量参数,避免手写错误
  • 对代码侵入性低,采用全注解的方式,开发简单
  • 方法参数名修改、新增、减少参数都可以直接生效,不用手动维护
  • 缺点:增加了开发成本,写接口还得再写一套参数配置

2.对前端开发来说

  • 后端只需要定义好接口,会自动生成文档,接口功能、参数一目了然
  • 联调方便,如果处理问题,直接测试接口,实时检查参数和返回值,就可以快速定位是前端还是后端的问题

3.对于测试

  • 但对于测试没有前端界面UI的功能,可以直接用它来测试接口
  • 操作简单,不用了解具体代码就可以操作
如何搭建一个swagger
  • 引入swagger的依赖
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.8.0</version>
</dependency>
  • springboot 整合swagger
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket productApi(){
        return new Docket(DocumentationType.SWAGGER_2).
                apiInfo(apiInfo()).
                select().
                apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).//添加ApiOpentaion注解的被扫描
                paths(PathSelectors.any()).
                build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder().
                title("swagger和springboot整合").
                description("swagger的api文档").
                version("1.0").build();
    }
}

swagger的注解:
swagger的核心在于注解,接下来就着重说一下swagger的注解

注解名称注解含义注解使用的地方注解参数注解含义
@EnableSwagger2开启swagger注解配置类上
@Api标识swagger识别的类Controller类上value
tags
description
url的路径值
如果设置这个值、value的值会被覆盖
对api资源的描述
@ApiIgore屏蔽显示某个Controller,开启后在swagger上不会在显示Controller类上value
@ApiOperation标识swagger识别的方法Controller类中的方法value
tags
description
basePath
position
produces
consumes
protocols
authorizations
hidden
response
responseContainer
httpMethod
code
extensions
notes
url的路径值
如果设置这个值、value的值会被覆盖
对api资源的描述
基本路径可以不配置
如果配置多个Api 想改变显示顺序位置
For example,"application/json,application/xml"
For example,"application/json,application/xml"
Possible values:http,https,ws,wss
高级特性认证时配置
配置为true将在文档中隐藏
返回的对象
这些对象是有效的“List”,“Set”or “Map”,其他无效
“GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“OPTIONS”and "PATCh"
http的状态码 默认200
扩展属性
用于提示内容
@ApiImpliciParam修饰方法中的参数用在@ApiImplicitParams注解中对,指定一个请求参数的各个方面paramType
name
value
dataType
required
defaultValue
参数放在哪个地方
参数代表的含义
参数名称
参数类型,有String/int,无用
是否必要
参数的默认值
@ApiImpliciParams修饰方法中的参数用在方法上包含一组参数说明@ApiImpliciParamApiImpliciParam的数组集合
@ApiResponse修饰方法的返回值方法上或方法的参数上code
message
class
方法返回值状态码
方法返回值信息
方法返回class
@ApiResponses响应集配置方法上或参数上@ApiResponseApiResponse的数组集合
@ApiParam映射方法上的参数方法的参数上name
value
defaultValue
allowableValues
required
access
allowMutiple
hidden
example
属性名称
属性值
默认属性值
可以不配置
是否属性必填
不过多描述
默认为false
隐藏该属性
举例子
@ApiModel用于类,表示对类进行说明,用于参数用实体类接受类上value
description
类名
描述
@ApiModelProperty标识一个类的属性类的字段上value
name
dateType
required
example
hidden
字段说明
重写属性名字
重写属性类型
是否必填
举例子
隐藏
在项目中如何集成swagger

在controller中使用注解

import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value = "测试TTestController",tags = {"测试访问接口"})
@RequestMapping("test")

public class TTestController {

    @ApiOperation(value = "添加测试数据")
    @PostMapping("/insertInfo")
    @ApiResponses(value = {
            @ApiResponse(code = 1000,message = "成功"),
            @ApiResponse(code = 1001,message = "失败"),
            @ApiResponse(code = 1002,message = "缺少参数",response = TestUser.class)
    })
    public String insertInfo(@ApiParam("用户名字") @RequestParam("userName") String userName,
                             @ApiParam(value = "年龄",allowEmptyValue = true) @RequestParam("age") Integer age){
        String username = userName;
        Integer Age = age;
        return username+age.toString();
    }
}
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "testUser",description = "用户")
public class TestUser {

    @ApiModelProperty(value = "用户名字", name = "userName", dataType = "String")
    private String userName;

    private Integer age;

    public Integer getAge() {
        return age;
    }

    public void setAge(Integer age) {
        this.age = age;
    }

    public String getUserName() {
        return userName;
    }

    public void setUserName(String userName) {
        this.userName = userName;
    }
}

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-q2hbyv2W-1585701064277)(/assets/img/1581553-20190122152913694-1597148667.png)]

访问本地连接
http://localhost:8080/swagger-ui.html

是那个用swagger需要注意的问题
  • 对于只有一个HttpServletRequest参数的方法,如果参数小于5个,推荐使用 @ApiImplicitParams的方式单独封装每一个参数;如果参数大于5个,采用定义一个对象去封装所有参数的属性,然后使用@APiParam的方式
  • 默认的访问地址:ip:port/swagger-ui.html#/,但是在shiro中,会拦截所有的请求,必须加上默认访问路径(比如项目中,就是ip:port/context/swagger-ui.html#/),然后登陆后才可以看到
  • 在GET请求中,参数在Body体里面,不能使用@RequestBody。在POST请求,可以使用@RequestBody和@RequestParam,如果使用@RequestBody,对于参数转化的配置必须统一
  • controller必须指定请求类型,否则swagger会把所有的类型(6种)都生成出来
  • swagger在生产环境不能对外暴露,可以使用@Profile({“dev”, “prod”,“pre”})指定可以使用的环境
总结

swagger作为一款辅助性的工具,能大大提升我们的和前端的沟通效率,接口是一个非常重要的传递数据的媒介,每个接口的签名、方法参数都非常重要。一个良好的文档非常重要,如果采用手写的方式非常容易拼写错误,而swagger可以自动化生成参数文档,这一切都加快了我们的沟通效率。并且可以替代postman的作用。实在是开发编程必备良品啊。

  • 0
    点赞
  • 3
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

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

余额充值