使用Swagger生成在线文档

怼烎@ 2023-10-09 16:39 67阅读 0赞

**目录**

1：Swagger介绍

2：使用

2.1：swaager集成boot依赖

2.2：配置文件中配置相关信息

2.3：在启动类中加入相关注解

2.4：测试

3：swagger常用注解

--------------------

## 1：Swagger介绍 ##

在前后端分离开发中通常由后端程序员设计接口，完成后需要编写接口文档，最后将文档交给前端工程师，前端工程师参考文档进行开发。

可以通过一些工具快速生成接口文档 ，通过Swagger生成接口在线文档 。

什么是Swagger？

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

Swagger是全球最大的OpenAPI规范（OAS）API开发工具框架，Swagger是一个在线接口文档的生成工具，前后端开发人员依据接口文档进行开发。 ([API Documentation & Design Tools for Teams | Swagger][API Documentation _ Design Tools for Teams _ Swagger])

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

## 2：使用 ##

### 2.1：swaager集成boot依赖 ###

在API工程添加swagger-spring-boot-starter依赖

<dependency>
                <groupId>com.spring4all</groupId>
                <artifactId>swagger-spring-boot-starter</artifactId>
                <version>1.9.0.RELEASE</version>
            </dependency>

### 2.2：配置文件中配置相关信息 ###

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

# swagger 文档配置
    swagger:
      title: "好课在线系统管理"
      description: "系统管理接口"
      base-package: com.xuecheng.system
      enabled: true
      version: 1.0.0

### 2.3：在启动类中加入相关注解 ###

在启动类中添加@EnableSwagger2Doc注解

@EnableSwagger2Doc
    @SpringBootApplication
    public class SystemApplication {
    
        public static void main(String[] args) {
            SpringApplication.run(SystemApplication.class,args);
        }
    }

### 2.4：测试 ###

启动服务：

![fc66ff90d06646b7a7c0d7b1b124aec0.png][]

可以看到文档页面已正常显示，但是可读性不是很高，可以使用swaager提供的一些注解来增强接口文档的可读性。

## 3：swagger常用注解 ##

Swaager的常用注解如下：

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

**@Api：修饰整个类，描述Controller的作用  
@ApiOperation：描述一个类的一个方法，或者说一个接口  
@ApiParam：单个参数描述  
@ApiModel：用对象来接收参数  
@ApiModelProperty：用对象接收参数时，描述对象的一个字段  
@ApiResponse：HTTP响应其中1个描述  
@ApiResponses：HTTP响应整体描述  
@ApiIgnore：使用该注解忽略这个API  
@ApiError ：发生错误返回的信息  
@ApiImplicitParam：一个请求参数  
@ApiImplicitParams：多个请求参数**

测试使用：

在类中添加注解，在方法上添加注解，增加可读性

@Slf4j
    @RestController
    @Api(value = "系统字典",tags = "系统字典查询接口")
    public class DictionaryController  {
    
        @Autowired
        private DictionaryService  dictionaryService;
        @ApiOperation("查询所有字典中的信息")
        @GetMapping("/dictionary/all")
        public List<Dictionary> queryAll() {
            return dictionaryService.queryAll();
        }
        @ApiOperation("查询指定编码所对应的详情信息")
        @GetMapping("/dictionary/code/{code}")
        public Dictionary getByCode(@PathVariable String code) {
            return dictionaryService.getByCode(code);
        }
    }

![278739f1fdf44579a689dc64abd20a2e.png][]

[GitHub - OAI_OpenAPI-Specification_ The OpenAPI Specification Repository]: https://github.com/OAI/OpenAPI-Specification
[API Documentation _ Design Tools for Teams _ Swagger]: https://swagger.io/
[fc66ff90d06646b7a7c0d7b1b124aec0.png]: https://img-blog.csdnimg.cn/fc66ff90d06646b7a7c0d7b1b124aec0.png
[278739f1fdf44579a689dc64abd20a2e.png]: https://img-blog.csdnimg.cn/278739f1fdf44579a689dc64abd20a2e.png