Softonic

Swagger 2.0-validerare

Steg 1 / 2
Nästa

Klistra in en Swagger 2.0-definition, i JSON eller YAML, för att kontrollera att den har versionsfältet swagger, ett info-objekt med title och version samt ett paths-objekt. Sökvägsposterna granskas för inledande snedstreck och för nycklar som inte är standardoperationer.

Så kontrollerar du en Swagger 2.0-fil

  1. 1

    Kopiera din definition

    Kopiera hela `swagger.json`- eller `swagger.yaml`-filen, med början på raden `swagger: "2.0"`.

  2. 2

    Klistra in den

    Klistra in den i fältet för OpenAPI- eller Swagger-dokument.

  3. 3

    Kör kontrollen

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

  4. 4

    Uppdatera och kontrollera igen

    Tillämpa rättningarna i din fil och klistra in den nya versionen tills rapporten är ren.

Vad som räknas som godkänt för Swagger 2.0

För en 2.0-fil godkänns versionskontrollen av en nyckel swagger på översta nivån. Verktyget kontrollerar inte att värdet är "2.0", så det fångar inte ett felaktigt nummer. Utöver versionen krävs info.title, info.version och ett paths-objekt.

Fält som är specifika för Swagger 2.0, till exempel host, basePath, schemes, definitions och securityDefinitions, granskas inte. En saknad host eller ett trasigt block definitions rapporteras inte.

Ett genomgånget exempel

{
  "swagger": "2.0",
  "info": { "title": "Shop API", "version": "1.0" },
  "paths": {
    "/products": {
      "get": { "summary": "List products" },
      "x-internal": true
    }
  }
}

Versionsfältet, info och paths finns alla, så det finns inga fel. Rapporten visar en varning:

Resultat Typ Varför
Unknown method ‘x-internal’ on /products. Varning Nyckeln är inte en standardoperation eller ett fält för sökvägsobjekt

Dokumentet redovisas ändå som giltigt, eftersom varningar inte blockerar giltigheten. Tilläggsnycklar från leverantörer som x-internal är tillåtna i Swagger 2.0, så du kan låta dem stå kvar.

Migrering från 2.0

Om du planerar att gå över till OpenAPI 3.x kan du klistra in den konverterade filen i samma ruta och jämföra resultaten. Kontrollen är densamma, med fältet openapi i stället för swagger. För det faktiska migreringsarbetet behöver du en fullständig konverterare och linter, eftersom det här verktyget inte översätter inställningar för definitions eller host.

När en snabb kontroll räcker

Swagger 2.0-definitioner lever ofta i flera år i repositorier och redigeras för hand. En snabb strukturkontroll är användbar när du tar över en sådan fil, när ett verktyg vägrar läsa in den och du misstänker ett saknat fält, eller när du slår ihop två filer och vill vara säker på att resultatet fortfarande har sina avsnitt info och paths. För de fullständiga reglerna för 2.0, inklusive definitions och säkerhetsinställningar, använd en särskild linter.

Kom ihåg att en ren rapport bara säger något om strukturen. Operationer utan svar, fel parametertyper och olösta referenser ligger utanför kontrollen, så testa filen även i ditt dokumentations- eller kodgenereringsverktyg.

Vanliga frågor

Nej. Det kontrollerar att fältet swagger eller openapi finns, inte vad det innehåller.

Nej. Bara versionsfältet, info-objektet, paths-objektet och posterna under varje sökväg granskas.

Ja. Texten läses först som JSON och som YAML om det misslyckas. Behåll indraget oförändrat när du klistrar in.

Sökvägsnivåns parameters, summary, description och servers finns på listan över godkända nycklar, så de utlöser inte varningen för okänd metod.

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