Powrót do realizacji
REALIZACJA
Pinpoint
Klient
Pinpoint
Branża
Applicant Tracking System
Produkt
Generator dokumentacji API
Data
2025
Umiejętności
Ruby on Rails
Graphiti
OpenAPI
O kliencie
Pinpoint to nowoczesna platforma typu Applicant Tracking System (ATS), zaprojektowana w celu uproszczenia złożonych procesów rekrutacyjnych w średnich i dużych przedsiębiorstwach. System wspiera zespoły HR na każdym etapie – od przyciągania talentów i zarządzania aplikacjami, po onboarding nowych pracowników. Rozwiązanie wyróżnia się elastycznością, pozwalając na efektywne zarządzanie rekrutacją oraz zapewnia bezpieczeństwo i zgodność z globalnymi standardami.
O projekcie
Głównym celem była optymalizacja pracy deweloperów Pinpoint poprzez pełną automatyzację generowania specyfikacji API. Projekt obejmował: Stworzenie narzędzia typu "plug-and-play" które automatycznie generuje schematy, przykłady zapytań i odpowiedzi na podstawie zasobów. Zgodność ze standardami: Zapewnienie pełnej kompatybilności generowanych plików JSON/YAML z platformą ReadMe.io. Konfigurowalność: możliwość elastycznego zarządzania tym, które zasoby mają być widoczne w publicznej dokumentacji.
Problem klienta
Klient korzysta z usługi ReadMe do generowania dokumentacji API na podstawie pliku openapi.yaml, który opisuje API w standardzie OpenAPI. Jednak plik openapi.yaml musi być aktualizowany ręcznie przy każdej zmianie w API implementowanym za pomocą Graphiti w Ruby on Rails. Graphiti jest potężnym frameworkiem, lecz mało popularnym, dlatego nie ma gotowych narzędzi automatyzujących generowanie dokumentacji. W efekcie zespół klienta spędzał znaczną część czasu na ręcznej edycji pliku YAML zamiast faktycznych prac deweloperskich i wprowadzania nowych funkcjonalności.
Wyzwania dla 2N
- Brak dostępu do kodu głównej aplikacji. Konieczność zrozumienia, jak Graphiti definiuje zasoby, ich relacje i schematy danych, wyłącznie na podstawie specyfikacji i przykładów.
- Kompatybilność z OpenAPI i ReadMe.io. Zapewnienie generowania specyfikacji w formacie zgodnym z OpenAPI (JSON i YAML), tak aby ReadMe.io pobierało ją bez błędów i mogło wyświetlać dokumentację w przyjaznej formie.
- Klient wskazał istniejący gem jako punkt wyjścia, ale wymagał on szeregu poprawek: naprawa kilku błędów, aktualizacja bibliotek, dostosowanie do nowszych wersji Graphiti/Rails.
80+
Automatycznie opisanych endpointów
Co zrobiliśmy
Obsługa wszystkich typów relacji i danych w Graphiti
Graphiti pozwala definiować różnorodne relacje (has_many, belongs_to, polymorphic, etc.) oraz typy pól. Trzeba było zapewnić, że generator poprawnie odwzoruje je w specyfikacji OpenAPI.
Generowanie przykładów zapytań, odpowiedzi i schematów
Dla każdej operacji HTTP trzeba było wygenerować przykładowe requesty, response’y oraz ich schematy. Zadbanie o czytelność i użyteczność tych przykładów w docelowej dokumentacji na ReadMe.io.
Konfiguracja w aplikacji Rails
Dodaliśmy initializer umożliwiający ustawienie podstawowych opcji, włączanie/wyłączanie poszczególnych zasobów i modyfikowanie dokumentacji za pomocą własnego kodu. Przygotowaliśmy instrukcję integracji w dokumentacji README gema.
Rezultat
Gem generujący dokumentację: dostarczony gem pozwala w prosty sposób włączyć automatyczne generowanie specyfikacji OpenAPI (JSON i YAML) z definicji Graphiti w Rails, w tym automatycznie aktualizować dokumentację w ReadMe.io w ramach CI.
Co osiągnęliśmy:
- Automatyzacja procesu: manualna edycja pliku openapi.yaml stała się zbędna. Po wprowadzeniu zmian w definicjach Graphiti wystarczy jedno polecenie, by wygenerować aktualną dokumentację.
- Oszczędność czasu deweloperów: Zamiast kilku godzin ręcznej pracy z YAML, generacja trwa kilka sekund.
- Łatwiejszy onboarding nowych deweloperów i tworzenie nowych integracji: pełne przykłady zapytań i odpowiedzi ułatwiają zrozumienie API, redukując liczbę pytań i nieporozumień.
Zobacz więcej naszych realizacji
LocalCaddie
Turystyka, Sport
Turystyka, Sport
LocalCaddie to firma, która dostrzegła lokalny problem i sposób na jego rozwiązanie na szerszą skalę. Projekt rozpoczął się jako MVP, ale miał ogromny potencjał. Został opracowany w mniej niż 6 tygodni! Kliknij, aby dowiedzieć się więcej!
Expandeo
Nieruchomości
Nieruchomości
Expandeo to warszawska firma zajmująca się nieruchomościami komercyjnymi, prowadzona przez zespół interdyscyplinarnych ekspertów z zakresu handlu detalicznego, nieruchomości, rozwoju biznesu, budownictwa i finansów. Firma koncentruje się na kompleksowym wsparciu sieci handlowych planujących ekspansję na polskim rynku. Dzięki ponad 10-letniemu doświadczeniu we współpracy z sieciami franczyzowymi i realizacji projektów nieruchomościowych, Expandeo opracowało unikalny system operacyjny dostosowujący się zarówno do rozwijających się firm, jak i korporacji.