CentOS Swagger支持哪些API格式 - 问答

CentOS环境下Swagger支持的API格式
Swagger（现归属于OpenAPI Initiative，通常指OpenAPI Specification，简称OAS）的核心是语言无关的API描述标准，其文档主要以JSON和YAML两种格式编写，这两种格式是Swagger生态中最基础、最广泛支持的API格式。

1. JSON格式

JSON（JavaScript Object Notation）是Swagger的传统支持格式，具有结构清晰、解析效率高、跨语言兼容性强等特点。Swagger UI、Swagger Editor等工具均可直接读取JSON格式的API文档，用于可视化展示和交互测试。例如，一个简单的Swagger 2.0 JSON文档结构如下：

{
  "swagger": "2.0",
  "info": {
    "title": "Sample API",
    "version": "1.0.0",
    "description": "A sample API to demonstrate Swagger on CentOS."
  },
  "host": "your_server_ip_or_domain",
  "basePath": "/",
  "schemes": ["http"],
  "paths": {
    "/api/hello": {
      "get": {
        "summary": "Returns a hello message",
        "responses": {
          "200": {
            "description": "An example response",
            "schema": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

这种格式适用于需要直接编辑或通过程序生成API文档的场景。

2. YAML格式

YAML（YAML Ain’t Markup Language）是另一种常见的Swagger支持格式，相比JSON，它更强调可读性，支持注释（JSON不支持），更适合人类编写和维护。YAML文档的结构与JSON类似，但语法更简洁。例如，上述JSON文档对应的YAML格式为：

swagger: '2.0'
info:
  title: Sample API
  version: 1.0.0
  description: A sample API to demonstrate Swagger on CentOS.
host: your_server_ip_or_domain
basePath: /
schemes:
  - http
paths:
  /api/hello:
    get:
      summary: Returns a hello message
      responses:
        '200':
          description: An example response
          schema:
            type: string

YAML格式是当前Swagger生态中更推荐的使用方式，尤其适合团队协作和文档管理。

补充说明

OpenAPI 3.0+格式：随着OpenAPI Specification的演进（如3.0、3.1版本），YAML和JSON仍然是核心格式，但新增了对组件复用（如components/schemas）、更灵活的参数定义（如content替代produces/consumes）等特性的支持。CentOS环境下，只要Swagger工具版本支持OpenAPI 3.0+，即可正常解析这些格式的文档。
框架集成中的格式：在CentOS上使用Spring Boot、Go-zero等框架时，通过Swagger注解或插件生成的API文档，默认也是以JSON或YAML格式输出（如Spring Boot的springfox-swagger2生成JSON格式，Go-zero的goctl swagger生成YAML格式），这些文档可直接导入Swagger UI进行可视化。

综上，CentOS环境下Swagger主要支持JSON和YAML两种API格式，其中YAML因可读性更强更常用，而JSON则更适合程序化处理。

0 赞

0 踩