接口调试神器——Swagger

最新推荐文章于 2024-10-26 11:25:41 发布

转载最新推荐文章于 2024-10-26 11:25:41 发布 · 586 阅读

1 ·

CC 4.0 BY-SA版权

原文链接：https://juejin.im/post/5ca5ab84f265da30d66b802a

文章标签：

#json #ui #java

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

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

Swagger介绍

最好的API构建工具。

自动生成在线接口文档；
集成接口在线调试；
使用非常简单；
社区活跃；

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>

复制代码