Kiểm tra & chuyển đổi OpenAPI API

Kiểm tra OpenAPI 3.0, 3.1, 3.2 và Swagger 2.0 theo schema chính thức, lint lỗi hay gặp, liệt kê endpoint, YAML ↔ JSON, nâng Swagger 2 lên OAS 3.

GETPOSThttps://apibox.io.vn/v1/openapi-tools

Tiện ích lập trình▶ Dùng thử online

Gửi tài liệu API ở spec (text YAML hoặc JSON, hoặc object JSON), dưới dạng body text, hoặc cho url của nó. Với action=validate (mặc định), tài liệu được kiểm tra theo JSON Schema chính thức của đúng phiên bản do OpenAPI Initiative công bố (Swagger 2.0, OpenAPI 3.0, 3.1 và 3.2, cập nhật hằng tuần) và danh sách lỗi được lọc còn những lỗi có ích: với các nhánh oneOf, chỉ báo lỗi của nhánh mà bạn nhiều khả năng định viết, kèm JSON pointer của từng lỗi.

Bộ lint có sẵn bổ sung những gì schema không thấy: $ref không trỏ được, operationId trùng, tham số path thiếu trong parameters hoặc không có trong đường dẫn, tham số path thiếu required: true, đường dẫn tương đương (/a/{id} và /a/{name}), security scheme chưa khai báo, operation không có response 2xx, GET có request body, URL server kết thúc bằng dấu gạch chéo, component không dùng tới, và thiếu mô tả, tag, contact hay licence (mức info). stats đếm số path, operation theo method, schema và server.

action=endpoints liệt kê mọi operation (method, path, operationId, summary, tags, tham số, kiểu nội dung của request body, mã response, security); action=convert đổi YAML sang JSON và ngược lại (to); action=upgrade chuyển Swagger 2.0 sang OpenAPI 3.0.3 (servers từ host / basePath / schemes, requestBody từ tham số body và formData, components, các flow security, viết lại $ref, x-nullable) rồi kiểm tra luôn kết quả. Không tải các file $ref bên ngoài. Tối đa 10 MB.

Tham số

Tên	Vị trí	Kiểu	Bắt buộc	Mặc định
`spec`	body	string	không		Tài liệu OpenAPI / Swagger: text YAML hoặc JSON, hoặc object JSON. Hoặc gửi body text thô.
`url`	body\|query	string	không		URL công khai của tài liệu, thay cho `spec`.
`action`	body\|query	string	không	`validate`	`validate` (schema + lint + thống kê), `endpoints`, `convert` (YAML ↔ JSON) hoặc `upgrade` (Swagger 2.0 → OpenAPI 3.0.3).
`to`	body\|query	string	không		`json` hoặc `yaml` cho convert / upgrade (mặc định: định dạng còn lại với convert, giữ nguyên với upgrade).
`lint`	body\|query	boolean	không	`true`	`false` để bỏ qua bộ lint.

Ví dụ

curl -X POST "https://apibox.io.vn/v1/openapi-tools" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spec":"openapi: 3.0.3\ninfo:\n  title: Shop API\n  version: 1.0.0\npaths:\n  /orders/{id}:\n    get:\n      summary: Get an order\n      responses:\n        '\''200'\'':\n          description: The order\n"}'

const res = await fetch('https://apibox.io.vn/v1/openapi-tools', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "spec": "openapi: 3.0.3\ninfo:\n  title: Shop API\n  version: 1.0.0\npaths:\n  /orders/{id}:\n    get:\n      summary: Get an order\n      responses:\n        '200':\n          description: The order\n"
  }),
});
const data = await res.json();
console.log(data);

import requests

res = requests.post(
    "https://apibox.io.vn/v1/openapi-tools",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"spec": "openapi: 3.0.3\ninfo:\n  title: Shop API\n  version: 1.0.0\npaths:\n  /orders/{id}:\n    get:\n      summary: Get an order\n      responses:\n        '200':\n          description: The order\n"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/openapi-tools');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"spec":"openapi: 3.0.3\\ninfo:\\n  title: Shop API\\n  version: 1.0.0\\npaths:\\n  /orders/{id}:\\n    get:\\n      summary: Get an order\\n      responses:\\n        \'200\':\\n          description: The order\\n"}',
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Kết quả trả về

{
  "openapi_version": "3.0.3",
  "format": "yaml",
  "title": "Shop API",
  "api_version": "1.0.0",
  "valid": false,
  "schema_valid": true,
  "errors": [],
  "lint": {
    "errors": 1,
    "warnings": 2,
    "infos": 4,
    "issues": [
      {
        "rule": "servers-defined",
        "severity": "warning",
        "path": "/servers",
        "message": "No servers: clients will use the document location as base URL"
      },
      {
        "rule": "operation-operationId",
        "severity": "warning",
        "path": "/paths/~1orders~1{id}/get",
        "message": "GET /orders/{id} has no operationId"
      },
      {
        "rule": "path-params-defined",
        "severity": "error",
        "path": "/paths/~1orders~1{id}/get",
        "message": "Path parameter {id} of GET /orders/{id} is not defined in parameters"
      },
      "…"
    ]
  },
  "stats": {
    "paths": 1,
    "operations": 1,
    "by_method": {
      "GET": 1
    },
    "tags": [],
    "schemas": 0,
    "security_schemes": [],
    "servers": [],
    "deprecated_operations": 0
  },
  "schema_used": "https://spec.openapis.org/oas/3.0/schema/2024-10-18"
}

Ứng dụng

Kiểm tra file OpenAPI trong CI trước khi xuất tài liệu hoặc sinh SDK
Tìm $ref hỏng và operationId trùng trong đặc tả lớn
Chuyển tài liệu Swagger 2.0 sang OpenAPI 3
Liệt kê toàn bộ endpoint của API bên thứ ba từ URL openapi.json

Hỏi đáp

Hỗ trợ những phiên bản nào?

Swagger 2.0 và OpenAPI 3.0.x, 3.1.x, 3.2.x, mỗi bản dùng JSON Schema chính thức từ spec.openapis.org.

Schema Object trong 3.1 có được kiểm tra không?

Schema 3.1 / 3.2 kiểm tra cấu trúc tài liệu; các schema bên trong được kiểm tra qua lint và việc phân giải $ref, không theo đầy đủ meta-schema JSON Schema.

Có đọc các $ref trỏ ra file ngoài không?

Không. Tham chiếu tới file hay URL khác được liệt kê ở mức info và không được tải; mọi tham chiếu nội bộ (#/...) đều được phân giải và kiểm tra.

Kiểm tra & chuyển đổi OpenAPI API

Tham số

Ví dụ

Kết quả trả về

Ứng dụng

Hỏi đáp

API liên quan

Tạo UUID

Phân tích biểu thức cron

Giờ & múi giờ