Softonic

Kontroll av obligatoriska fält i OpenAPI

Steg 1 / 2
Nästa

Innan du lämnar över en API-beskrivning till en kollega, en kund eller ett dokumentationsverktyg ska du se till att de obligatoriska fälten finns på plats. Klistra in ditt dokument ovan så bekräftar verktyget versionsfältet, info.title, info.version och paths och listar det som saknas.

Så kontrollerar du de obligatoriska fälten

  1. 1

    Klistra in dokumentet

    Klistra in din specifikation som JSON eller YAML, även om den fortfarande är under arbete.

  2. 2

    Kör kontrollen

    Gå vidare till resultatsteget. Varje saknat fält visas som ett eget fel.

  3. 3

    Lägg till det som saknas

    Lägg till de angivna fälten i din fil med hjälp av kodexemplen nedan.

  4. 4

    Kontrollera igen

    Klistra in den uppdaterade specifikationen och kör den igen tills inga fel visas.

De fyra obligatoriska delarna

Fält Var det hör hemma Exempel
Versionsfält Översta nivån openapi: 3.0.3 eller swagger: "2.0"
info.title Inuti info title: Orders API
info.version Inuti info version: 1.0.0
paths Översta nivån paths: med minst din första rutt

Värdet för info.version är versionen av ditt eget API, inte av OpenAPI-specifikationen. Många utelämnar det eftersom specifikationens version redan står överst.

Ett genomgånget exempel där allt saknas

servers:
  - url: https://api.example.com

Det här lilla dokumentet saknar alla obligatoriska delar. Rapporten listar tre fel:

Resultat Typ
Missing ‘openapi’ or ‘swagger’ version field. Fel
Missing ‘info’ object. Fel
Missing ‘paths’ object. Fel

När hela info-objektet saknas rapporterar verktyget bara det felet och listar inte title och version separat. Lägg till info med båda fälten, så visar nästa körning om något fortfarande saknas.

Startskelett

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders:
    get:
      summary: List orders

Det här skelettet klarar alla kontroller av obligatoriska fält. Byt ut namnen mot dina egna och bygg vidare därifrån. Svar, scheman och säkerhet ingår inte i den här kontrollen.

När du ska köra kontrollen

Kör den när du startar en ny specifikation från början, efter att du har genererat en från kod och innan du skickar den till någon som ska importera den i ett annat verktyg. Många importverktyg stannar vid det första saknade obligatoriska fältet med ett kort meddelande, så om du fångar alla i ett svep sparar du flera omgångar. Det är också en påminnelse för nybörjare, som ofta glömmer info.version eller utelämnar paths när de skissar ett API.

När de obligatoriska fälten klarar kontrollen är nästa användbara tillägg en kort description under info, en post i servers och en operationId för varje operation. Ingen av dem kontrolleras här, men de gör specifikationen lättare att läsa och att omvandla till klientkod.

Vanliga frågor

Nej. Fältet openapi anger vilken version av specifikationen du använder. info.version är versionen av ditt eget API, till exempel 1.0.0.

Nyckeln måste finnas som ett objekt, och den här kontrollen kräver inga rutter inuti det. Lägg till riktiga rutter innan du publicerar.

Kontrollerna för title och version körs först när objektet info finns. Lägg till det och kör om för att se om dess fält är kompletta.

Nej. Här krävs bara versionsfältet, info, title, version och paths. Detaljer på operationsnivå granskas inte.

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