接口调试神器——Swagger

本文详细介绍如何使用Swagger构建RESTful API,包括依赖添加、配置示例及常用注解使用,并演示了如何自定义主题及导出接口文档。

摘要生成于 C知道 ,由 DeepSeek-R1 满血版支持, 前往体验 >

Swagger介绍

最好的API构建工具。

  1. 自动生成在线接口文档;
  2. 集成接口在线调试;
  3. 使用非常简单;
  4. 社区活跃;

Hello World

以springboot工程为例;

添加swagger依赖

<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
</dependency>
<!-- swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
</dependency>
复制代码

编写Swagger配置

package com.iflytek.demo.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;

/**
 * @author caojiantao
 * @mail: jtcao2@iflytek.com
 * @description: swagger配置类
 * @date 2018/10/30 17:18
 */
@Configuration
@EnableSwagger2
public class Swagger2 {

    @Bean
    public Docket swaggerPlugin() {
        List<Parameter> parameters = new ArrayList<>();
        Parameter token = new ParameterBuilder()
                .name("X-Token")
                .description("登陆令牌")
                .modelRef(new ModelRef("string"))
                .parameterType("header")
                .build();
        parameters.add(token);
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.iflytek.demo"))
                .build()
                .globalOperationParameters(parameters);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger入门示例")
                .description("一些借口描述")
                .version("1.0")
                .build();
    }
}
复制代码

编写测试接口

package com.iflytek.demo.swagger;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author caojiantao
 * @mail: jtcao2@iflytek.com
 * @description: 一句话描述这个类
 * @date 2018/11/1 14:51
 */
@RestController
public class TestController {

    @GetMapping("/get")
    public ResultDTO get(Query query) {
        System.out.println(query);
        return new ResultDTO<>(200, "88888888", "get请求成功");
    }

    @PostMapping("/post")
    public ResultDTO post(@RequestBody Query query) {
        System.out.println(query);
        return new ResultDTO<>(200, "88888888", "post请求成功");
    }
}
复制代码

hello world

运行项目,进入swagger-ui页面:http://127.0.0.1:8080/swagger-ui.html

注解修饰

@API

类级注解,说明该类的作用;

@Api(tags = {"a", "b"}, description = "描述")
复制代码

效果图示:

@ApiOperation

方法级注解,说明该方法的作用;

@ApiOperation(value = "获取资源", notes = "请注意")
复制代码

效果图示:

@ApiImplicitParams @ApiImplicitParam

方法级注解,描述接口(一组)参数;

@ApiOperation(value = "获取资源", notes = "请注意")
@ApiImplicitParams({
    @ApiImplicitParam(paramType = "query", name = "name", value = "查询名称", required = true, dataType = "string"),
    @ApiImplicitParam(paramType = "query", name = "type", value = "查询类别", dataType = "int"),
})
复制代码

效果图示:

@ApiResponses @ApiResponse

方法级注解,描述接口(一组)响应码描述;

@ApiResponses({
    @ApiResponse(code = 500, message = "服务器异常")
})
复制代码

效果图示:

@ApiModel @ApiModelProperty

类级注解,详细描述一个model;

@ApiModel(value = "响应实体")
public class ResultDTO<T> implements Serializable {

    @ApiModelProperty(value="响应码",name="code",example="200")
    private Integer code;
    private  T data;
    private String message;
}
复制代码

效果图示:

功能测试

自定义主题

官方UI可能不太符合部分审美,推荐一款国人开源项目:github.com/caojiantao/…

使用非常简单,引入依赖:

<dependency>
    <groupId>com.github.caspar-chen</groupId>
    <artifactId>swagger-ui-layer</artifactId>
    <version>1.0.0</version>
</dependency>

复制代码

访问地址:http://127.0.0.1:8080/docs.html

效果图示:

接口文档导出

Mock数据

导出接口JSON文件

http://127.0.0.1:8080/v2/api-docs

YApi平台

添加项目

导入JSON接口,同步数据

操作成功

生产环境去除

swagger.enable=true

参考文章

  1. Swagger官网

转载于:https://juejin.im/post/5ca5ab84f265da30d66b802a

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

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

抵扣说明:

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

余额充值