wprowadzenie OpenAPI jako artefakt budowania

[ad-m]

W #106 wprowadziliśmy dokumentacje OpenAPI automatycznie generowaną na podstawie aplikacji. Stanowi ona ma pełną specyfikacje jakie funkcjonalności systemu będą udostępnione. To oznacza, że mamy konieczność ścisłego kontrolowania rozwoju dokumentacji, gdyż zazwyczaj zmiany w dokumentacji oznacza zmiany w interfejsie API, które są istotne dla innych zespołów (front-end, integracje), więc konieczna jest odpowiednia komunikacja.

W #161 dostrzegliśmy jak dokumentacja jest istotna dla recenzji. Z tego względu warto sprawić, aby na tym etapie dokumentacja była zachowywana jako artefakt budowania. Pozwoli to nam na śledzenie zmian w dokumentacji dla każdego zmiany, czyli kontrolę w czasie. Obecnie prymitywnie na CI. Potem może zapewnimy skuteczniejsze UI dla analizowania tego, ale zacznijmy gromadźmy dane (zwykle w projektach dokumentacje API archiwizuje w odrębnym repozytorium Git automatycznie aktualizowanym podobnie jak Microsoft - https://github.com/Azure/azure-rest-api-specs ).

GitHub Actions wspiera możliwość składowania artefaktów budowania. Dokumentacja: https://help.github.com/en/actions/automating-your-workflow-with-github-actions/persisting-workflow-data-using-artifacts#uploading-build-and-test-artifacts Uruchamiamy aplikacje w ramach procesu CI: https://github.com/watchdogpolska/small_eod/blob/dev/backend-project/contrib/github/script.sh#L14 .

Po zamknięciu actions/upload-artifact#27 warto, aby w logach był odpowiedni link do dokumentacji Swagger & ReDoc, która umożliwi podgląd obecnej dokumentacji.

Zakres zmian:

• zapisy dokumentacji OpenAPI do pliku YAML & JSON,
• wysyłanie dokumentacji OpenAPI jako build-artifact
• linkowanie do Swagger & ReDoc

[ad-m]

See #185

[bukowa]

Czy:

1. Utworzenie nowego repozytorium X dla SDK
2. Utworzenie i dodanie klucza SSH w opcjach repozytorium X (deploy keys) z write access
3. Konfiguracja github worfklow aby w określonych przypadkach commitował te artefakty do repozytorium X z uzyciem tego klucza?

Jest rozwiązaniem?
Można by nawet odwzorować strukturę tak, aby repozytorium SDK posiadało branche i commity, które odzwierciedlają stan small_eod z SDK w danym czasie.

Do tego bardzo zastanawia mnie, jak poprzez github workflow, tworzyć wiadomośći pod pull requestami, np. z artefaktów (w tym przypadku mogłyby to być linki do repozytorium SDK odzwierciedlające dany commit). Np. tutaj, pod "AccessLint" dana akcja workflow mogłaby zwracać dane. Pewnie można to osiągnąc przy pomocy aplikacji, ale takie akcje z workflow były by bardzo proste.

[ad-m]

Linkowania nie ma, ale pozostałe elementy zostały wykonane. Mamy nawet diff.