Softonic

OpenAPI controle van verplichte velden

Stap 1 / 2
Volgende

Voordat u een API-beschrijving aan een collega, een klant of een documentatiegenerator geeft, moet u zeker weten dat de verplichte velden aanwezig zijn. Plak uw document hierboven: de tool bevestigt het versieveld, info.title, info.version en paths en somt op wat ontbreekt.

De verplichte velden controleren

  1. 1

    Plak het document

    Plak uw specificatie als JSON of YAML, ook als die nog niet af is.

  2. 2

    Start de controle

    Ga naar de stap met resultaten. Elk ontbrekend veld verschijnt als een eigen fout.

  3. 3

    Voeg ontbrekende onderdelen toe

    Voeg de opgesomde velden toe aan uw bestand met de fragmenten hieronder.

  4. 4

    Controleer opnieuw

    Plak de bijgewerkte specificatie en voer de controle opnieuw uit tot er geen fouten meer worden getoond.

De vier verplichte onderdelen

Veld Waar het hoort Voorbeeld
Versieveld Hoogste niveau openapi: 3.0.3 of swagger: "2.0"
info.title Binnen info title: Orders API
info.version Binnen info version: 1.0.0
paths Hoogste niveau paths: met minstens uw eerste route

De waarde van info.version is de versie van uw eigen API, niet van de OpenAPI-specificatie. Mensen laten dit vaak weg omdat de versie van de specificatie al bovenaan staat.

Een uitgewerkt voorbeeld waarin alles ontbreekt

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

Dit kleine document bevat geen van de verplichte onderdelen. Het rapport somt drie fouten op:

Bevinding Type
Versieveld ‘openapi’ of ‘swagger’ ontbreekt. Fout
Object ‘info’ ontbreekt. Fout
Object ‘paths’ ontbreekt. Fout

Wanneer het hele info-object ontbreekt, meldt de tool die ene fout en somt hij titel en versie niet afzonderlijk op. Voeg info toe met beide velden, dan laat de volgende run zien of er nog iets ontbreekt.

Startskelet

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

Dit skelet slaagt voor elke controle op verplichte velden. Vervang de namen door uw eigen namen en bouw er vanuit verder aan. Responses, schema’s en beveiliging vallen niet onder deze controle.

Wanneer u deze controle moet draaien

Draai hem wanneer u een specificatie helemaal opnieuw begint, nadat u er een uit code hebt gegenereerd, en voordat u hem naar iemand stuurt die hem in een andere tool gaat importeren. Veel importeurs stoppen bij het eerste ontbrekende verplichte veld met een korte melding. Als u ze allemaal in één keer vindt, bespaart u een paar rondes. Het is ook een handige herinnering voor beginners, die bij het schetsen van een API vaak info.version vergeten of paths weglaten.

Nadat de verplichte velden slagen, zijn de volgende nuttige toevoegingen een korte description onder info, een servers-vermelding en een operationId bij elke bewerking. Die worden hier niet gecontroleerd, maar ze maken de specificatie leesbaarder en makkelijker om te zetten in clientcode.

Veelgestelde vragen

Nee. Het veld openapi geeft aan welke versie van de specificatie u gebruikt. info.version is de versie van uw eigen API, zoals 1.0.0.

De sleutel moet als object bestaan, en deze controle vereist geen routes erin. Voeg echte routes toe voordat u publiceert.

De controles op titel en versie draaien alleen als het object info bestaat. Voeg het toe en draai opnieuw om te zien of de velden compleet zijn.

Nee. Hier zijn alleen het versieveld, info, title, version en paths verplicht. Details op bewerkingsniveau worden niet onderzocht.

Gerelateerde tools

Webpack-configuratiegenerator

Maak een webpack.config.js voor webpack 5 voor gewoon JavaScript, React of Vue: TypeScript, Babel, CSS of Sass, afbeeldingen, HtmlWebpackPlugin, een devserver en de npm install-regel.

SVG-golfgenerator

Genereer een vloeiende SVG-golfscheiding voor headers en footers met instelbare amplitude, frequentie, kleur en positie boven of onder. Kopieer de SVG-code.

Protocol Buffers-decoder

Decodeer Protobuf-bytes lokaal uit hex, Base64, Base64URL, tekst of een bestand, bekijk veldinterpretaties en exporteer een privérapport.

XSD-validator

Valideer een XML-document tegen een XSD-schema en rapporteer discrepanties tussen elementen en typen, inclusief de exacte regelnummers.

XML-formatter

Maak XML-documenten netjes op met consistente inspringing en spoor welgevormdheidsfouten op met exacte regelnummers.

XML naar JSON

Zet XML-documenten om naar schone JSON, waarbij attributen, tekstknopen en arrays waar nodig behouden blijven. Drie stijlen: compact, Badgerfish of letterlijk.

Tool beschikbaar in andere talen

Handleidingen en toepassingen