openapi-spec-generation

Umiejętność do tworzenia, utrzymywania i walidacji specyfikacji OpenAPI 3.1 dla interfejsów REST. Automatyzuj generowanie dokumentacji API z istniejącego kodu, projektuj kontrakty API przed implementacją lub łącz oba podejścia. Idealna do generowania SDK klientów, konfiguracji portali dokumentacji i zapewniania zgodności implementacji z założeniami specyfikacji.

1. Zainstaluj umiejętność w swoim środowisku agenta, dodając repozytorium wshobson/agents do ścieżki wtyczek dokumentacji.

2. Przygotuj materiał źródłowy — jeśli masz istniejący kod API, zbierz definicje endpointów i schematy danych; jeśli projektujesz od zera, przygotuj koncepcję zasobów i operacji.

3. Wybierz podejście: design-first (napisz specyfikację przed kodem dla nowych API), code-first (wygeneruj ze starego kodu) lub hybrid (adnotuj kod i generuj specyfikację).

4. Użyj szablonu Complete API Specification jako punkt wyjścia — zawiera strukturę OpenAPI 3.1.0, sekcje info, servers, paths i components z przykładami autentykacji i rate limitingu.

5. Zdefiniuj wszystkie endpointy w sekcji paths, schematy danych w components/schemas oraz metody bezpieczeństwa w components/securitySchemes.

6. Waliduj gotową specyfikację — upewnij się, że każdy endpoint ma opisane parametry, request body, response codes i przykładowe odpowiedzi, a następnie użyj specyfikacji do generowania dokumentacji lub SDK klientów.