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注解如下：