Softonic

OpenAPI-validerare

Steg 1 / 2
Nästa

Klistra in ett OpenAPI- eller Swagger-dokument, i JSON eller YAML, så kontrollerar den här valideraren dess kärnstruktur. Den bekräftar att dokumentet kan parsas, att det har ett versionsfält openapi eller swagger, ett info-objekt med titel och version samt ett paths-objekt, och markerar sedan vägar som inte börjar med snedstreck och okända HTTP-metoder. Det är en snabb strukturkontroll, inte en fullständig JSON Schema-validerare.

Så går valideringen till

  1. 1

    Klistra in dokumentet

    JSON eller YAML, för OpenAPI 2 (Swagger) eller OpenAPI 3.

  2. 2

    Parsa det

    Valideraren parsar dokumentet som JSON och faller tillbaka på YAML-parsning om det misslyckas.

  3. 3

    Kontrollera de obligatoriska fälten

    Den bekräftar ett versionsfält `openapi` eller `swagger`, ett `info`-objekt med `title` och `version` samt ett `paths`-objekt.

  4. 4

    Skanna vägarna

    Varje väg kontrolleras för inledande snedstreck, och varje operationsnyckel jämförs mot kända HTTP-metoder.

  5. 5

    Läs rapporten

    Fel blockerar giltigheten; varningar pekar på vägar utan inledande snedstreck och okända metoder.

Vad den här valideraren kontrollerar

Kontroll Resultat vid fel
Dokumentet parsas som JSON eller YAML Fel
Fält openapi eller swagger finns Fel
info-objekt finns Fel
info.title finns Fel
info.version finns Fel
paths-objekt finns Fel
Varje väg börjar med / Varning
Operationsnycklar är kända HTTP-metoder Varning

Ett dokument som passerar varje fel rapporteras som strukturellt giltigt. Varningar blockerar inte giltigheten; de lyfter fram sådant som är värt att åtgärda.

Vad den inte kontrollerar

Det här är en strukturkontroll, inte en fullständig specifikationsvaliderare. Den gör inte följande:

  • validerar inte varje nod mot den officiella JSON Schema för din version;
  • löser inte $ref-referenser eller bekräftar att komponenterna de pekar på finns;
  • kontrollerar inte att vägparametrar deklareras och används konsekvent;
  • verifierar inte att operationId-värden finns eller är unika;
  • rapporterar inte radnummer för fel.

För det djupet, kör en dedikerad CLI-validerare som redocly lint, swagger-cli validate eller spectral lint. Använd det här verktyget för en snabb rimlighetskontroll innan du checkar in (commit) eller delar en specifikation.

OpenAPI-versioner i praktiken

Version Anmärkningar
Swagger 2.0 Fortfarande brett använd; använder swagger: "2.0"
OpenAPI 3.0.x Den vanligaste 3.x-linjen
OpenAPI 3.1.0 Anpassad till JSON Schema 2020-12

Den här valideraren accepterar antingen fältet openapi (3.x) eller fältet swagger (2.0), så alla dessa klarar versionskontrollen.

Ett minimalt dokument som klarar sig

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users

Varje obligatoriskt fält finns, den enda vägen börjar med snedstreck, och get är en känd metod, så det rapporteras som strukturellt giltigt.

Vanliga frågor

Swagger var det ursprungliga namnet på specifikationen, som donerades till Linux Foundation 2015 och bytte namn till “OpenAPI” från version 3.0. “Swagger” avser nu verktygen (Swagger UI, Swagger Editor). Själva specifikationen är OpenAPI. Den här valideraren accepterar både versionsfältet swagger (2.0) och openapi (3.x).

Nej. Den kontrollerar kärnstrukturen: att dokumentet kan parsas, har ett versionsfält, ett info-objekt med titel och version samt ett paths-objekt, och varnar för vägar utan inledande snedstreck och okända metoder. Den validerar inte varje nod mot den officiella JSON Schema. Använd redocly lint eller spectral lint för det.

Nej. Den följer inte $ref-referenser och kontrollerar inte att komponenterna de pekar på finns. För referenser mellan filer, bunta först ihop dokumentet med ett verktyg som redocly bundle eller swagger-cli bundle, och kör sedan en fullständig validerare.

Nej. Den granskar bara dokumentet du klistrar in, inte din körande kod. Den kan inte avgöra om ditt API faktiskt returnerar det som specifikationen beskriver. Kontraktstestverktyg som Dredd eller Schemathesis gör det.

Relaterade verktyg

Webpack-konfigurationsgenerator

Skapa en webpack.config.js för webpack 5 med vanlig JavaScript, React eller Vue: TypeScript, Babel, CSS eller Sass, bilder, HtmlWebpackPlugin, en utvecklingsserver och raden för npm install.

Protocol Buffers-avkodare

Avkoda Protobuf-byte lokalt från hex, Base64, Base64URL, text eller fil, granska fälttolkningar och exportera en privat rapport.

YAML till JSON

Omvandla YAML-konfiguration till JSON för verktyg och API:er som bara accepterar JSON. Hanterar ankare, merge-nycklar och nästlade strukturer.

XSD-validerare

Validera ett XML-dokument mot ett XSD-schema och rapportera element- och typavvikelser med exakta radnummer.

Generator för platshållarbilder

Skapa en bild på 1–4000 px med egna färger och text, ladda ned PNG eller kopiera webbadress och HTML.

XML-formaterare

Snygga till XML-dokument med konsekvent indrag och fånga formfel med exakta radnummer.

Verktyget finns på andra språk