😄
xlzy520
  • README
  • 执笔
    • 2017
      • 01 网站动态标题的两种方式
      • 02 RN App 外部唤醒踩坑记
    • 2018
      • 01 图片加解密二三事
      • 02 优雅实现 BackTop
      • 03 Vue 一键导出 PDF
      • 04 不一样の烟火
      • 05 Python 之禅
      • 06 Python 文件操作
    • 2019
      • 01 Aurora 食用指南
      • 02 Godaddy 域名找回记事
      • 03 一个接口的诞生
      • 04 SpringMVC 前后端传参协调
      • 05 主题集成友链访问统计功能
      • 06 Github Style 博客主题
      • 07 动态加载 JS 文件
      • 08 WebSocket 心跳重连机制
      • 09 洗牌算法实现数组乱序
      • 10 React Hook 定时器
      • 11 Fetch data with React Hooks
      • 12 字符编码の小常识
      • 13 WSL 安装 Docker 实录
      • 14 Eriri comic reader
  • 书斋
    • ES6 标准入门
      • 01 变量声明与解构赋值
      • 02 语法的扩展
      • 03 数据类型与数据结构
      • 04 Proxy 和 Reflect
      • 05 异步编程 Promise
      • 06 Iterator 和 for of 循环
      • 07 Generator 函数
      • 08 Async 函数
      • 09 Class 类
    • JavaScript 设计模式
      • 01 基础知识
      • 02 设计模式(上)
      • 03 设计模式(下)
      • 04 设计原则和编程技巧
  • 前端
    • JavaScript
      • 01 JavaScript 秘密花园
      • 02 JavaScript 正则技巧
      • 03 从浏览器解析 JS 运行机制
      • 04 Canvas 基础用法
      • 05 Flex 弹性布局
      • 06 Blob Url And Data Url
      • 07 函数节流与函数防抖
      • 08 排序算法初探
    • Node
      • 01 Node Tips
      • 02 七天学会 NodeJS
    • Note
      • 01 Note
      • 02 Snippets
      • 03 Interview
      • 04 Git
      • 05 Docker
      • 06 Line
    • React
      • 01 React Props Children 传值
      • 02 Use a Render Prop!
      • 03 React Hook
      • 04 React 和 Vue 中 key 的作用
    • Vue
      • 01 Vue Tips
      • 02 Vue 构建项目写入配置文件
      • 03 Vue 项目引入 SVG 图标
  • 后端
    • Java
      • 01 浅析 Java 反射
      • 02 Java 服务端分层模型
    • Note
      • 01 Note
      • 02 Linux
      • 03 MySQL
    • Spring
      • 01 Spring Boot
      • 02 Spring Data
      • 03 JPA
      • 04 Swagger
      • 05 AOP
      • 06 SSM
    • Project
      • 01 微信点餐系统
由 GitBook 提供支持
在本页
  • 添加依赖
  • 配置参数
  • 配置类
  • 使用

这有帮助吗?

  1. 后端
  2. Spring

04 Swagger

Swagger 提供了一套通过代码和注解自动生成文档的方法。

添加依赖

<!-- 自动生成描述 API 的 json 文件 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- 将 json 文件解析出来,用一种更友好的方式呈现 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

配置参数

swagger:
  title: API标题
  description: API描述
  version: 1.0.0
  terms-of-service-url: https://chanshiyu.com/
  base-package: com.chanshiyu
  contact:
    name: Chanshiyu
    url: https://chanshiyu.com/
    email: me@chanshiyu.com

配置类

/**
 * conf.SwaggerConfig.java
 * @Configuration 告诉 Spring Boot 需要加载这个配置类
 * @EnableSwagger2 启用 Swagger2
 */
@Configuration
@EnableSwagger2
@ConditionalOnClass(EnableSwagger2.class)
@Data
@Component
@ConfigurationProperties(prefix = "swagger")
public class SwaggerConfig {

    /**
     * API页面标题
     */
    private String title;

    /**
     * API描述
     */
    private String description;

    /**
     * API版本号
     */
    private String version;

    /**
     * API接口包路径
     */
    private String basePackage;

    /**
     * 服务条款地址
     */
    private String termsOfServiceUrl;

    /**
     * 联系人
     */
    private Contact contact;

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(title)
                .description(description)
                .termsOfServiceUrl(termsOfServiceUrl)
                .version(version)
                .contact(contact)
                .build();
    }
}

使用

注解名称

使用说明

@Api

描述一个 API 类

@ApiImplicitParam

描述一个请求参数

@ApiImplicitParams

描述一组请求参数

@ApiModel

描述一个返回的对象

@ApiModelProperty

描述一个返回的对象参数

@ApiOperation

描述一个 API 方法

@ApiParam

描述一个方法的参数

@ApiResponse

描述一个请求响应

@ApiResponses

描述一组请求响应

@ApiIgnore

表示忽略

@Api(tags = "买家商品", description = "买家商品相关 Rest API")
public class BuyerOrderController {
    @ApiOperation(value="订单详情")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "openid", value = "买家 openid", required = true, dataType = "String"),
            @ApiImplicitParam(name = "orderId", value = "订单 ID", required = true, dataType = "String")
    })
    @GetMapping("/detail")
    public ResultVO<OrderDTO> detail(@RequestParam("openid") String openid,
                                     @RequestParam("orderId") String orderId) {
        OrderDTO orderDTO = buyerService.findOrderOne(openid, orderId);
        return ResultVOUtil.success(orderDTO);
    }
}
/**
 * 商品信息
 */
@Data
@ApiModel("商品类目详情")
public class ProductVO {

    @ApiModelProperty("类目名称")
    @JsonProperty("name")
    private String categoryName;

    @ApiModelProperty("类目类型")
    @JsonProperty("type")
    private Integer categoryType;

    @ApiModelProperty("商品列表")
    @JsonProperty("list")
    private List<ProductInfoVO> productInfoVOList;
}

启动项目访问路径查看文档:http://192.168.51.242:8080/swagger-ui.html#/。

上一页03 JPA下一页05 AOP

最后更新于5年前

这有帮助吗?

参考文章:

在 Spring Boot 项目中使用 Swagger 文档