# swagger-demo

**Repository Path**: sayYi/swagger-demo

## Basic Information

- **Project Name**: swagger-demo
- **Description**: openapi 与 swagger
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-12-23
- **Last Updated**: 2021-12-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 接口文档案例

openapi的元数据信息介绍：<https://swagger.io/specification/>

官方文档：<https://springdoc.org/>

添加openapi的依赖后，访问 <http://server:port/context-path/swagger-ui.html> 即可查看api文档

api涉及到一个信息组合继承的问题。
api中说明的信息如果和功能性注解不同，就会有问题。比如api中声明数据不能为空，但是功能注解说是非必填字段，那么就需要考虑以谁为准的问题。
这属于文档生成框架需要考虑的问题。

需要注意的是，使用了api工具不代表就真的可以将文档集成在项目中了。

- api文档的书写，本质上还是依赖于程序员自己的习惯，工具只是提供了表单项，但是具体怎么写还是依赖于开发人员自身。只能说某种程度上给文档维护提供了便利，但是感觉还是看个人，不会写注释的人，使用再便利的工具也无济于事。
- api声明只能到 controller，只是针对接口的，也就是说更像是面向前端用户提供的。只是涵盖controller的文档，其他的地方还是需要自己去规范。

这种东西，本质上没啥神奇的。关键还是在于开发人员自己有良好的注释习惯，否则在文档方面的帮助其实有限，甚至有没有都一样。


## openapi 与 swagger

openapi定义了声明接口信息的规范（数据内容，数据格式），swagger作为实现，将注解中的数据提取输出为满足openapi要求的文档


## 使用

主要区分四个层次的注解

- 应用级别 `@OpenAPIDefinition`
- 控制器级别 `@Tag`
- 方法级别 `@Operation`
- Model、Model Field `@Schema`

其他的看注释就知道大概怎么回事了