深入解析Swagger Petstore示例项目中的OpenAPI 3.0规范

郝茜润Respected

于 2025-06-01 09:01:18 发布

阅读量309

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00429/article/details/148360054

深入解析Swagger Petstore示例项目中的OpenAPI 3.0规范

OpenAPI-Specification 项目地址: https://gitcode.com/gh_mirrors/open/OpenAPI-Specification

什么是Swagger Petstore示例

Swagger Petstore是OpenAPI规范中最经典的示例项目之一，它模拟了一个宠物商店的API服务。这个示例完美展示了如何使用OpenAPI 3.0规范来描述RESTful API的各种元素，包括路径、操作、参数、响应和数据结构等。

OpenAPI 3.0规范基础结构

让我们先来看这个示例的基本结构：

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Swagger Petstore",
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "http://petstore.swagger.io/v1"
    }
  ],
  "paths": {},
  "components": {}
}

openapi: 声明使用的OpenAPI规范版本
info: 包含API的元信息，如版本、标题和许可证
servers: 定义API的基础URL
paths: 定义API的具体端点
components: 定义可重用的组件，如数据模型

API端点详解

1. 获取宠物列表接口

"/pets": {
  "get": {
    "summary": "List all pets",
    "operationId": "listPets",
    "tags": ["pets"],
    "parameters": [
      {
        "name": "limit",
        "in": "query",
        "description": "How many items to return at one time (max 100)",
        "required": false,
        "schema": {
          "type": "integer",
          "maximum": 100,
          "format": "int32"
        }
      }
    ],
    "responses": {
      "200": {
        "description": "A paged array of pets",
        "headers": {
          "x-next": {
            "description": "A link to the next page of responses",
            "schema": { "type": "string" }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Pets" }
          }
        }
      }
    }
  }
}

这个GET接口展示了几个重要特性：

查询参数limit的定义，包括类型、格式和最大值限制
分页响应设计，通过x-next头部提供下一页链接
使用$ref引用组件中定义的Pets模型

2. 创建宠物接口

"post": {
  "summary": "Create a pet",
  "operationId": "createPets",
  "tags": ["pets"],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": { "$ref": "#/components/schemas/Pet" }
      }
    },
    "required": true
  },
  "responses": {
    "201": { "description": "Null response" }
  }
}

POST接口特点：

定义了请求体，要求必须提供
请求体使用JSON格式，引用Pet模型
成功响应返回201状态码

3. 获取特定宠物信息接口

"/pets/{petId}": {
  "get": {
    "summary": "Info for a specific pet",
    "operationId": "showPetById",
    "tags": ["pets"],
    "parameters": [
      {
        "name": "petId",
        "in": "path",
        "required": true,
        "description": "The id of the pet to retrieve",
        "schema": { "type": "string" }
      }
    ],
    "responses": {
      "200": {
        "description": "Expected response to a valid request",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Pet" }
          }
        }
      }
    }
  }
}

这个接口展示了：

路径参数的定义和使用
如何标记参数为必需
成功响应返回单个Pet对象

数据模型定义

在components/schemas部分定义了三个主要模型：

1. Pet模型

"Pet": {
  "type": "object",
  "required": ["id", "name"],
  "properties": {
    "id": { "type": "integer", "format": "int64" },
    "name": { "type": "string" },
    "tag": { "type": "string" }
  }
}

必须包含id和name字段
id是64位整数
tag是可选字段

2. Pets模型

"Pets": {
  "type": "array",
  "maxItems": 100,
  "items": { "$ref": "#/components/schemas/Pet" }
}

表示Pet对象的数组
限制最大数量为100

3. Error模型

"Error": {
  "type": "object",
  "required": ["code", "message"],
  "properties": {
    "code": { "type": "integer", "format": "int32" },
    "message": { "type": "string" }
  }
}