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

ASCII-tabellreferens

Full ASCII-tabell från 0 till 127 med decimal-, hex-, oktal- och binärvärden samt notation för numeriska HTML-referenser, inklusive NUL, LF och DEL.

HTML-teckenreferens

En sökbar lista över HTML-entiteter med deras namngivna och numeriska koder samt kopiering med ett klick för specialtecken och symboler.

Referens för kortkommandon

Sök dokumenterade standardkommandon för VS Code, Chrome och Bash med GNU Readline i macOS, Windows och Linux.

E-postvalidator

Validera en e-postadress: RFC 5322-syntaxkontroll, live-slagning av MX-poster samt detaljer om lokal del, domän och längd. Ingen e-post skickas.

EditorConfig-generator

Generera en .editorconfig-fil med dina regler för indragsstil och -storlek, radslut, teckenuppsättning och blanksteg för enhetlig formatering i alla IDE:er och editorer.

HTML-formaterare

Formatera HTML lokalt i webbläsaren med indrag på två eller fyra blanksteg. HTML laddas inte upp eller valideras.

Verktyget finns på andra språk