Softonic

OpenAPI 3.1-validerare

Steg 1 / 2
Nästa

Klistra in ett OpenAPI 3.1-dokument i JSON eller YAML för att kontrollera dess översta struktur. Verktyget letar efter fältet openapi, ett info-objekt med title och version samt ett paths-objekt. Det är en strukturkontroll, så schemanyckelord i 3.1 valideras inte, och några mönster som fungerar bra i 3.1 ger en varning eller ett fel som du bör känna till.

Så kontrollerar du ett 3.1-dokument

  1. 1

    Klistra in din 3.1-specifikation

    Klistra in dokumentet med `openapi: 3.1.0` (eller ett annat 3.1.x-värde) i fältet, som JSON eller YAML.

  2. 2

    Kör kontrollen

    Gå vidare till resultatsteget för att se fel och varningar.

  3. 3

    Läs noterna om 3.1

    Kontrollera om en markerad punkt är ett verkligt misstag eller ett av de 3.1-mönster som beskrivs nedan.

  4. 4

    Komplettera med en fullständig linter

    Använd en komplett validerare för reglerna i JSON Schema 2020-12 när strukturen är i ordning.

Så hanterar verktyget 3.1-filer

Version 3.1 anpassar scheman till JSON Schema 2020-12. Den här validerraren läser inte in några scheman alls. Den granskar bara den översta nivån och sökvägsposterna, så funktioner i 3.1-scheman, som typlistor eller const, godkänns eller underkänns inte här. Själva versionsvärdet kontrolleras inte heller: varje openapi-fält räknas som närvarande.

Två 3.1-mönster att hålla utkik efter

Mönster i din 3.1-fil Vad verktyget rapporterar
webhooks-objekt och inget paths-objekt Fel: Missing ‘paths’ object.
trace-operation under en sökväg Varning: Unknown method ‘trace’ on the path
$ref som nyckel på ett sökvägsobjekt Varning: Unknown method ‘$ref’ on the path

OpenAPI 3.1 tillåter att ett dokument bara beskriver webhooks och utelämnar paths. Det här verktyget kräver paths, så en sådan fil rapporteras med ett fel, trots att specifikationen tillåter den. Om du lägger till ett tomt paths: {}-objekt klarar filen kontrollen.

Metoderlistan som används här är get, post, put, patch, delete, head, options, plus parameters, summary, description och servers. Metoden trace finns i specifikationen men står inte på listan, så den ger en varning som du kan ignorera om den är avsiktlig. Varningar gör inte dokumentet ogiltigt.

Ett genomgånget exempel

openapi: 3.1.0
info:
  title: Events API
  version: 2.0.0
webhooks:
  newEvent:
    post:
      summary: Event delivered

Resultat: ett fel, “Missing ‘paths’ object.” Lägg till paths: {} så klarar strukturen kontrollen.

När du ska använda detta och när du ska gå längre

Använd sidan för att bekräfta att en 3.1-fil har rätt form innan du öppnar en pull request eller delar den med en partner. Kontrollerna är snabba och meddelandena enkla. När strukturen stämmer behöver 3.1-schemareglerna ändå en fullständig linter, eftersom de flesta verkliga misstag finns där: ogiltiga typdeklarationer, trasiga referenser och saknade svarsdefinitioner. Se de två stegen som komplement snarare än som alternativ.

Om en flaggad varning är avsiktlig, till exempel trace, skriv en notering om det i din pull request så att granskarna inte undrar. Varningar ändrar aldrig det giltiga resultatet, så de kan finnas kvar. Felen är de punkter som ska åtgärdas innan filen delas.

Vanliga frågor

Nej. Det tittar inte in i schemaobjekt, så nyckelord i JSON Schema 2020-12 kontrolleras inte. Det täcker bara den översta strukturen och sökvägsposterna.

Kontrollen kräver ett paths-objekt. En 3.1-fil med bara webhooks saknar det, så den rapporterar ett fel för saknad paths. Lägg till ett tomt paths: {} för att klara kontrollen.

Nej. Den kontrollerar bara att ett openapi- eller swagger-fält finns, inte vilket värde det har.

Inte nödvändigtvis. trace är en giltig operation i specifikationen. Verktyget tar bara inte med den i sin lista över kända metoder.

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.

XSD-validerare

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

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.

XML-formaterare

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

XML till JSON

Omvandla XML-dokument till ren JSON, med bevarade attribut, textnoder och arrayer där det behövs. Tre stilar: kompakt, Badgerfish eller literal.

Verktyget finns på andra språk

Guider och användningsområden