Tworzenie specyfikacji za pomocą edytora specyfikacji

Wyświetlasz dokumentację Apigee Edge.
Otwórz dokumentację Apigee X. info

Twórz i weryfikuj specyfikacje OpenAPI bez pisania kodu za pomocą edytora specyfikacji.

Otwieranie edytora specyfikacji

Otwórz specyfikację OpenAPI w edytorze specyfikacji zgodnie z opisem w sekcjach poniżej:

Na ilustracji poniżej widać specyfikację interfejsu Petstore API otwartą w edytorze specyfikacji:

Jak widać na poprzednim rysunku, edytor specyfikacji umożliwia:

  • Utwórz specyfikację OpenAPI, aby modelować interfejs API w formacie JSON lub YAML w panelu po lewej stronie.
  • W panelu po prawej stronie wyświetli się wygenerowana automatycznie dokumentacja API.
  • Sprawdzaj specyfikację pod kątem zgodności ze standardem specyfikacji OpenAPI podczas pisania.
  • Zapisz specyfikację OpenAPI lub zamknij specyfikację i anuluj zmiany.

Pomoc dotycząca formatów JSON i YAML

JSON (JavaScript Object Notation) to lekki format wymiany danych używany do reprezentowania prostych struktur danych i tablic asocjacyjnych. Więcej informacji znajdziesz na stronie https://www.json.org.

YAML (YAML Ain't Markup Language) to standard serializacji i reprezentacji danych, który zapewnia składnię, którą można mapować na struktury danych, takie jak listy, tablice asocjacyjne i skalary. Więcej informacji znajdziesz na stronie https://yaml.org.

Zarówno JSON, jak i YAML są czytelne dla komputera, ale też łatwe do odczytania i zrozumienia dla człowieka. Na ilustracji poniżej porównano 2 krótkie fragmenty tej samej specyfikacji OpenAPI zapisanej w formatach JSON i YAML:

JSON a YAML

Weryfikowanie specyfikacji

Edytor specyfikacji weryfikuje specyfikację OpenAPI pod kątem zgodności ze standardem specyfikacji OpenAPI. Jeśli podczas pisania w specyfikacji OpenAPI wystąpią błędy, w edytorze specyfikacji w górnej części prawego panelu pojawi się okno błędu. Zawiera ono więcej informacji o błędach i powiązanych z nimi numerach wierszy, dzięki czemu możesz je łatwo poprawić.

Błędy

Zapisywanie specyfikacji

Aby zapisać specyfikację OpenAPI, na górnym pasku nawigacyjnym kliknij Zapisz.

Jeśli zapisujesz specyfikację po raz pierwszy, pojawi się prośba o wpisanie nazwy pliku. Jeśli nie podasz nazwy pliku, domyślnie będzie to „Bez tytułu”. Możesz później zmienić jego nazwę.

Zamykanie specyfikacji

Aby zamknąć specyfikację OpenAPI bez zapisywania zmian, na górnym pasku nawigacyjnym kliknij Anuluj. Wrócisz do listy specyfikacji.