Softonic

Sprawdzenie wymaganych pól OpenAPI

Krok 1 / 2
Dalej

Zanim przekażesz opis API koledze z zespołu, klientowi albo generatorowi dokumentacji, upewnij się, że wymagane pola są na miejscu. Wklej dokument powyżej, a narzędzie potwierdzi pole wersji, info.title, info.version i paths oraz wypisze wszystko, czego brakuje.

Jak sprawdzić wymagane pola

  1. 1

    Wklej dokument

    Wklej specyfikację w formacie JSON lub YAML, nawet jeśli nadal jest w trakcie pracy.

  2. 2

    Uruchom sprawdzenie

    Przejdź do kroku wyników. Każde brakujące pole pojawia się jako osobny błąd.

  3. 3

    Dodaj brakujące elementy

    Dodaj wymienione pola do swojego pliku, korzystając z poniższych fragmentów.

  4. 4

    Sprawdź ponownie

    Wklej zaktualizowaną specyfikację i uruchom ją ponownie, aż nie będzie błędów.

Cztery wymagane elementy

Pole Gdzie się znajduje Przykład
Pole wersji Najwyższy poziom openapi: 3.0.3 lub swagger: "2.0"
info.title Wewnątrz info title: Orders API
info.version Wewnątrz info version: 1.0.0
paths Najwyższy poziom paths: z co najmniej pierwszą trasą

Wartość info.version to wersja Twojego własnego API, a nie wersja specyfikacji OpenAPI. Ludzie często ją pomijają, bo wersja specyfikacji jest już na górze dokumentu.

Przykład ze wszystkim brakującym

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

Ten maleńki dokument nie ma żadnego z wymaganych elementów. Raport wymienia trzy błędy:

Wynik Typ
Missing ‘openapi’ or ‘swagger’ version field. Błąd
Missing ‘info’ object. Błąd
Missing ‘paths’ object. Błąd

Gdy cały obiekt info jest nieobecny, narzędzie zgłasza tylko ten jeden błąd i nie wymienia osobno title i version. Dodaj info z oboma polami, a przy następnym uruchomieniu zobaczysz, czy któreś z nich nadal brakuje.

Szkielet startowy

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

Ten szkielet przechodzi wszystkie kontrole wymaganych pól. Zastąp nazwy własnymi i rozbudowuj dalej. Odpowiedzi, schematy i zabezpieczenia nie są częścią tej kontroli.

Kiedy uruchomić to sprawdzenie

Uruchamiaj je, gdy zaczynasz nową specyfikację od zera, po wygenerowaniu jej z kodu oraz przed wysłaniem komuś, kto zaimportuje ją do innego narzędzia. Wiele narzędzi importujących zatrzymuje się na pierwszym brakującym wymaganym polu z krótkim komunikatem, więc wychwycenie wszystkich naraz oszczędza kilka rund. To też przypomnienie dla nowicjuszy, którzy przy szkicowaniu API często zapominają o info.version albo pomijają paths.

Gdy wymagane pola przechodzą kontrolę, kolejnymi przydatnymi dodatkami są krótki description pod info, wpis servers i operationId przy każdej operacji. Żadne z nich nie jest tu sprawdzane, ale ułatwiają czytanie specyfikacji i generowanie kodu klienta.

Najczęściej zadawane pytania

Nie. Pole openapi określa, której wersji specyfikacji używasz. info.version to wersja Twojego własnego API, na przykład 1.0.0.

Klucz musi istnieć jako obiekt, a ta kontrola nie wymaga żadnych tras w jego wnętrzu. Dodaj prawdziwe trasy przed publikacją.

Kontrole title i version uruchamiają się tylko wtedy, gdy obiekt info istnieje. Dodaj go, a potem uruchom kontrolę ponownie, aby sprawdzić, czy jego pola są kompletne.

Nie. Tutaj wymagane są tylko pole wersji, info, title, version i paths. Szczegóły na poziomie operacji nie są badane.

Powiązane narzędzia

Generator konfiguracji webpack

Utwórz plik webpack.config.js dla webpacka 5 do czystego JavaScriptu, Reacta lub Vue: TypeScript, Babel, CSS lub Sass, obrazy, HtmlWebpackPlugin, serwer deweloperski i polecenie npm install.

Generator kolorów analogicznych

Twórz pięciokolorowe palety analogiczne z dowolnego koloru bazowego: klasyczną trójkę, dwie zewnętrzne barwy oraz wartości hex, RGB i HSL.

Walidator XSD

Waliduj dokument XML wobec schematu XSD i zgłaszaj niezgodności elementów i typów z dokładnymi numerami wierszy.

Generator fikcyjnych numerów telefonu

Generuj do 50 fikcyjnych numerów z oficjalnie zastrzeżonych zakresów w pięciu krajach.

Kod na obraz

Wklej kod, ustaw motyw, kolory, rozmiar czcionki, odstępy, nagłówek i numery wierszy, sprawdź podgląd canvas i pobierz PNG. Renderowanie zwykłego tekstu, bez podświetlania składni.

Dekoder Protocol Buffers

Dekoduj lokalnie bajty Protobuf z zapisu hex, Base64, Base64URL, tekstu lub pliku, analizuj pola i eksportuj prywatny raport.

Narzędzie jest dostępne w innych językach

Poradniki i zastosowania