OpenAPI样式验证器是一种创建具有可理解的描述，示例和持续使用命名约定的API规格的工具。
验证器可帮助开发人员确定OpenAPI规格中的问题。使用定义的规则，您可以准确描述API规范的外观。这些规格可以自动检查，结果可以用于代码评论，甚至可以在构建管道中使用规则违规导致构建中断。
。 完整的描述和命名惯例
验证器检查OpenAPI模式的各种对象，从信息对象以及关联的联系人和许可对象开始。通常根本没有提供这些细节。在这里，您可以看到一个示例，流行的PetStore示例如何提供详细信息。
{
"info": {
"version": "1.0.0",
"title": "Swagger Petstore",
"description": "A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification",
"termsOfService": "http://swagger.io/terms/",
"contact": {
"name": "Swagger API Team",
"email": "apiteam@swagger.io",
"url": "http://swagger.io"
},
"license": {
"name": "Apache 2.0",
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
}
}
}
我们将仔细研究的下一个对象是操作对象。但是，让我们从路径对象开始。路径对象包含通往现有端点（路径项）的所有路径。单个路径（/宠物）包含描述允许哪种HTTP方法的操作。
{
"/pets/{id}": {
"get": {
"description": "Returns a user based on a single ID, if the user does not have access to the pet",
"operationId": "find pet by id",
"parameters": [
{
"name": "id",
"in": "path",
"description": "ID of pet to fetch",
"required": true,
"schema": {
"type": "integer",
"format": "int64"
}
}
],
}
}
}
OpenAPI样式验证器检测是否存在某些属性，例如，上面列表中缺少属性“摘要”。相反，存在一个“描述”。如果您以这种方式进行了配置，则缺少属性是错误。
让我们看看OpenAPI样式验证器如何检查数据类型描述。数据类型在OpenAPI规范中定义为架构对象，可以在请求或响应中引用（例如“ $ ref”：“＃/components/components/chemas/newpet”）。验证器可以检查所有模式属性是否存在描述和示例，而不是空的。
{
"NewPet": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
}
},
}
如果我们查看上面列表中的新PET架构对象，我们找不到描述和示例。 API规范中的示例和描述使文档更具可理解。
现在让我们继续进行命名惯例。命名约定有助于使API易于使用。 OpenAPI样式验证器支持许多不同的约定，我们可以将其应用于路径，路径参数，查询参数，cookie，标题和属性。命名惯例是：下划线案例（蛇案），骆驼盒，我们从java和javaScript中知道的，以及所谓的连字符案件，也称为烤肉案。
选项并启动OpenAPI样式验证器
有了我们现在已经学到的定义规则，我们可以控制OpenAPI规范的外观。我们有什么样的选择？有一些布尔选项，例如“ vasionoperationOperationID”，实际上，每个操作都有一个ID。选项“ vericationerationsummary”要求操作还具有描述。但是，还有一些字符串类型选项，例如PathnamingConfention，ParameternAmingConconcention，PathParameNingConconnevention和QueryparamnamingConconcention。有了这些选项，我们可以确定元素是否应遵循，例如下划线案例或骆驼案命名约定。
那么，我们如何启动验证器？ maven命令看起来像这样：
mvn openapi-style-validator:validate
对于Maven，必须在pom.xml中配置OpenAPI样式验证器插件，必须排除io.swagger.v3依赖项，否则使用了库的较新版本，不幸的是，该版本与该版本不兼容的版本与版本不兼容。 OpenAPI样式验证器。如以下列表，可以将每个选项添加为XML标签下的参数，例如。以文本内容为true或fals
<plugin>
<groupId>org.openapitools.openapistylevalidator</groupId>
<artifactId>openapi-style-validator-maven-plugin</artifactId>
<version>1.8</version>
<configuration>
<inputFile>petstore-expanded.json</inputFile>
</configuration>
<dependencies>
<dependency>
<groupId>org.openapitools.empoa</groupId>
<artifactId>empoa-swagger-core</artifactId>
<version>2.0.0</version>
<exclusions>
<exclusion>
<groupId>io.swagger.core.v3</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
</plugin>
，顺便说一句，使用默认配置，我们为PETSTORE示例获得以下结果：
[INFO] --- openapi-style-validator:1.8:validate (default-cli) @ openapitools-validator-mvn-example ---
[INFO] Validating spec: petstore-expanded.json
[ERROR] OpenAPI Specification does not meet the requirements. Issues:
[ERROR] *ERROR* in Operation GET /pets "summary" -> This field should be present and not empty
[ERROR] *ERROR* in Operation GET /pets "tags" -> The collection should be present and there should be at least one item in it
[ERROR] *ERROR* in Operation POST /pets "summary" -> This field should be present and not empty
[ERROR] *ERROR* in Operation POST /pets "tags" -> The collection should be present and there should be at least one item in it
[ERROR] *ERROR* in Operation GET /pets/{id} "summary" -> This field should be present and not empty
[ERROR] *ERROR* in Operation GET /pets/{id} "tags" -> The collection should be present and there should be at least one item in it
[ERROR] *ERROR* in Operation DELETE /pets/{id} "summary" -> This field should be present and not empty
[ERROR] *ERROR* in Operation DELETE /pets/{id} "tags" -> The collection should be present and there should be at least one item in it
[ERROR] *ERROR* in Model "NewPet", property "name", field "example" -> This field should be present and not empty
[ERROR] *ERROR* in Model "NewPet", property "name", field "description" -> This field should be present and not empty
[ERROR] *ERROR* in Model "NewPet", property "tag", field "example" -> This field should be present and not empty
[ERROR] *ERROR* in Model "NewPet", property "tag", field 'description' -> This field should be present and not empty
[ERROR] *ERROR* in Model "Error", property "code", field 'example' -> This field should be present and not empty
[ERROR] *ERROR* in Model "Error", property "code", field 'description' -> This field should be present and not empty
[ERROR] *ERROR* in Model "Error", property "message", field "example" -> This field should be present and not empty
[ERROR] *ERROR* in Model "Error", property "message", field "description" -> This field should be present and not empty
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.342 s
链接
OpenAPI Style Validator
Petstore Beispiel
Validation example