Swagger Najlepsze praktyki

Question

Obecnie definiuję interfejs Rest API i zamierzam użyć Swagger, aby go udokumentować. Już zacząłem definiować moje specyfikacje interfejsu API za pomocą Specyfikacji Open Api w YAML w Swagger-Editor.

Następnie, rozumiem, że dam ten plik do Swagger-Codegen wygenerować implementację serwera, a także do Swagger-UI (którego statyka pliki będą poprzednio wklej do mojego serwera), aby odsłonić interaktywna dokumentacja.

Według Swagger jest to podejście odgórne z góry do dołu.

Ale później prawdopodobnie będę musiał zmodyfikować ten interfejs API i chcę to zrobić za pomocą tego żmudnego pliku YAML, który został wcześniej zdefiniowany, aby API było łatwe do zmienienia przez kogokolwiek (i agnostyka językowego).

1. Czy sposób, aby to zrobić, aby zmodyfikować plik definicji, a następnie ponowne wykorzystanie Swagger-Codegen? Dzięki temu podejściu, tak myślę, że nie mogę nawet lekko zmodyfikować API bezpośrednio w kodzie serwera implementacji bez ryzykowania posiadania przestarzałej dokumentacji.

i gdybym wybrał zrobić oddolne podejście(poprzez Swagger rdzeniem adnotacji), będę powstrzymać wszystkie moje dalsze modyfikacje występują w kodzie serwera wdrażania, a mój plik początkowy definicja nigdy już nie nadają się do użytku.

2. Kolejne pytanie brzmi: czy istnieje wspólny sposób radzenia sobie ze Swagger, gdy chcemy zmodyfikować API zarówno poprzez plik specyfikacji, jak i przez kod serwera implementacji (przypuszczam, że plik, który Swagger-core może wygenerować mnie z mojego kodu, nigdy nie będzie wyglądał jak mój początkowy, który zdefiniowałem ręcznie).

Dziękuję za uwagi.

Answer 1

Aby zachować dokumentację interfejsu API, najlepszym sposobem działania, jaki mogę zasugerować, jest zastosowanie podejścia hybrydowego.

Początkowo, gdy musisz opracować masę, przejdź do podejścia odgórnego. Spowoduje to zmniejszenie początkowej konfiguracji i wysiłku związanego z kodowaniem. To podstawowa idea każdego kodegena.

Następnie, jeśli chodzi o konserwację interfejsów API lub dodawanie kilku nowych każdego dnia (lub tygodnia), stosuj podejście oddolne. Będziesz już mieć poprzedni kod, jedyne, co musisz zrobić, to dodać więcej adnotacji lub definicji interfejsu API.

Przejście od góry do dołu iteracyjnie pokonuje cel konserwacji kodu. Płyty kotłowe i wygenerowany przez siebie kod służą do szybkiego uruchomienia, a nie do utrzymania.

Answer 2

Moja opinia może być stronnicza.

Dla klienta API nie powinno być potrzeby dostosowywania go w większości przypadków.Jeśli okaże się, że musisz dostosować go do swoich wymagań, warto rozpocząć dyskusję przez https://github.com/swagger-api/swagger-codegen/issues/new (a także sprawdź, jakie są dostępne opcje, aby dostosować wyjście, np. Dla PHP, uruchom java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php)

Dla serwera Zwykle programiści muszą skupić się tylko na logice biznesowej/aplikacji i regenerować kod pośredniczący serwera podczas dodawania/usuwania/aktualizowania punktów końcowych (ale nie sądzę, aby wszystkie kody pośredniczące serwera mogły to osiągnąć).

Oświadczenie: I Jestem najlepszym współpracownikiem do Swagger Codegen