概述
OpenAPI规范（以前称为Swagger规范）标准化了REST API的文档语言，并且是跨平台的。我们可以使用YAML或JSON格式创建OpenAPI文档。
另一方面，Swagger是一个工具集合，用于实现和处理这个标准。有些是免费的，有些是开源的，还有一些是商业的。这些工具帮助我们设计、文档化和使用REST API。
本文将指导我们如何在OpenAPI文档中格式化文本描述。
1. OpenAPI编辑器
有几个工具支持我们创建OpenAPI文档。一些流行的选择包括：
还有其他一些编辑器提供了创建OpenAPI文档的支持。然而，最流行和广泛使用的编辑器是Swagger Editor。因此，我们将借助Swagger Editor学习如何格式化我们的OpenAPI文档。
2. YAML与JSON格式化
OpenAPI文档可以使用JSON或YAML表示。然而，在使用YAML时，格式化文档更为直观。
例如，为了标记单词或句子为标题，我们可以在YAML中使用以下片段：
description: |
# This is a heading in *italics*
This is in the next line
This is in **bold**
YAML表示法使用|（管道符）来表示多行的标量字面值。
现在，让我们用JSON定义相同的内容：
{
"description": "# This is a heading in *italics*\nThis is in the next line\n\nThis is in **bold**
}
相比之下，JSON表示法中的转义序列使得格式化显得不直观。因此，我们将只关注用YAML编写的OpenAPI规范文档的格式化技巧。
最后，OpenAPI规范允许在所有级别对description字段进行格式化。因此，根据规范，只要description字段允许，我们就可以对其进行格式化，且description字段遵循CommonMark格式。
现在，让我们通过格式化增强我们的API文档。
3. 标题
就像HTML中的<h1>到<h6>标题一样，我们可以使用Markdown标题来突出显示文本。一个#代表一个标题。我们可以使用#多达六级来强调文本，数字越大，文本强调程度越低。
带有#的文本比带有#######的文本更醒目且更大。
例如，考虑以下YAML：
openapi: 3.0.1
info:
title: Petstore
description: |
# Pet Store APIs
## This is a sample Petstore server
### Contains APIs to manage the pet store
#### Note that the APIs support Basic Authentication and OAUTH
##### The samples contain Request and Response models
###### There are status codes defined as well
Swagger会渲染为：
4. 文本强调
为了提高description文本的可读性，我们可以使其加粗或斜体。
将文本放在**和**之间，或者在\_和\_之间，会使文本加粗。同样地，将文本放在*和*之间，或者_和_之间会使文本斜体。例如，对于以下YAML：
openapi: 3.0.1
info:
title: Petstore
description: |
## This document contains
**Pet Store APIs** *Note: All the APIs return application/json*.
__User APIs__ _Note: These APIs contain attachments and only support image/jpeg as the content type_
Swagger将渲染为：
5. 表格
接下来，我们来看看如何在OpenAPI文档中添加表格。
添加表格需要遵循一组规则：每列的表格应以|（管道符）开始和结束，每个表头之间至少应有一个-（连字符）。但是，-的数量没有限制。
例如，让我们为POST API添加一个表格来定义HTTP状态码：
paths:
/pet:
post:
tags:
- pet
description: |
**The below table defines the HTTP Status codes that this API may return**
| Status Code | Description | Reason |
| ---------------- | ------------| -----------------------------------|
| 201 | CREATED | If a pet is created successfuly. |
| 400 | BAD REQUEST | If the request is not valid. |
| 401 | UNAUTHORIZED| If the credentials are invalid. |
Swagger生成如下内容：
6. 列表
现在，让我们看看如何格式化描述文本以包含列表。
6.1. 有序列表
描述文本的项目应以数字后跟.（句点）开头。不过，项目的编号顺序并不重要。例如：
description: |
1. Available
3. Pending
1. Sold
description: |
1. Available
200. Pending
30. Sold
description: |
1. Available
100. Pending
50. Sold
都会生成相同的输出：
1. Available
2. Pending
3. Sold
项目的编号取决于起始项目。例如，如果从10开始编号，后续项目将被编号为11、12等。以下YAML：
description: |
10. Available
120. Pending
50. Sold
将生成：
10. Available
11. Pending
12. Sold
同样，有序子列表的规则也适用。将子列表缩进到其父项。例如，考虑以下YAML：
description: |
1. Available
2. Pending
1. Pending in Store
200. Pending in Cart
3. Sold
这将生成一个带有子列表的无序列表。请注意，子列表的分隔符混合使用。混合使用分隔符会产生相同的结果。
6.2. 无序列表
使用*（星号）或+（加号）或-（连字符）创建无序列表。也就是说，列表中的每个项目都应以其中一个符号开头。例如：
description: |
* Available
* Pending
* Sold
description: |
+ Available
+ Pending
+ Sold
description: |
- Available
- Pending
- Sold
上述所有片段都将生成无序列表。
同样，要生成无序子列表，只需将子列表项目与其父项目一起缩进，并以*、+或-开头。例如，以下YAML：
- Available
- Pending
* Pending in Store
+ Pending in Cart
- Sold
将生成一个带有子列表的无序列表。注意分隔符的混合使用。混合使用分隔符会产生相同的结果。
最后，让我们将所有这些放在一起，形成一个YAML：
/pet/findByStatus:
get:
summary: Finds Pets by status
description: |
__Below is the list of valid status of the Pet__
1. Available
2. Pending
1. Pending in the cart
2. Pending in the store
3. Sold
**Below is the list of HTTP Status code this API may return**
* 200 - OK
* 400 - Bad Request. The API returns below status codes related to content-type and accept headers
+ 415 - Unsupported Media Type
- 406 - Not Acceptable
* 401 - Unauthorized
* 405 - Method not supported
此YAML将生成：
7. 其他
8. 结论
在这篇文章中，我们了解了如何在OpenAPI文档的description字段中进行格式化。YAML标量字面值使我们在整个文档中都能格式化description。因此，OpenAPI文档可以包含任何或所有支持的构造，如列表、表格和图像。
良好的文档化和格式化的API可以提高易用性。毕竟，我们都希望有易于集成和使用的API。