Swagger使用指南

1.介绍

OpenAPI 规范（OpenAPI Specification 简称OAS）是 Linux 基金会的一个项目，试图通过定义一种用来描述 API 格式或 API 定义的语言，来规范 RESTful 服务开发过程，目前版本是 V3.2.0，并且已经发布并开源在 github 上。

Swagger是全球最大的 OpenAPI 规范（OAS）API 开发工具框架，Swagger 是一个在线接口文档的生成工具，前后端开发人员依据接口文档进行开发。

2.Java集成Swagger

SpringBoot 可以集成 Swagger，Swaager 根据 Controller 类中的注解生成接口文档 ，只要添加 Swagger 的依赖和配置信息即可使用它。

1.添加依赖

<!-- Spring Boot 集成 swagger -->
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
</dependency>

2.配置

在 bootstrap.yml 中配置 swagger 的扫描包路径及其它信息，base-package 为扫描的包路径，扫描 Controller 类。

server:
  servlet:
    context-path: /content
  port: 8080
#swagger配置
swagger:
  title: "xxx系统"
  description: "xxx"
  base-package: com.han.content
  enabled: true
  version: 1.0.0

3.启动

在启动类中添加 @EnableSwagger2Doc 注解，启动服务，访问 http://localhost:8080/content/swagger-ui.html查看接口信息

注意：路径要替换为自己项目的端口

下图为 swagger 接口文档的界面：

可以发现接口文档中的接口名为 swagger 默认的接口名，不易阅读

此时就需要添加注解来对接口、变量等进行注释

3.注解的使用

在 Java 类中添加 Swagger 的注解即可生成 Swagger 接口，常用 Swagger 注解如下：