ElevenLabs: kaip iš vienos OpenAPI specifikacijos generuojami dokumentai, SDK ir pavyzdžiai

ElevenLabs parodė savo inžinerinį procesą, kuriame kiekvienas viešas API endpoint aprašomas vienoje vietoje backend'e, o iš gyvai veikiančios OpenAPI specifikacijos automatiškai generuojama API dokumentacija, Python ir JavaScript SDK, savaitinis changelog, kodo asistentų „skills“ ir pavyzdinės programos. Pavyzdžiu imta „merge proposals“ funkcija, dėl kurios atsirado septyni nauji dokumentacijos puslapiai ir naujas metodas abiejuose SDK (versija 2.71). Dalį žingsnių atlieka DI agentai, tačiau kiekvienas jų atidaro pull request, kurį peržiūri ir sulieja žmogus.
Pilna santrauka
Vienas endpointas, penki paviršiai0:00
ElevenLabs video pristato, kaip vienas naujas API endpointas automatiškai pasiekia penkis skirtingus paviršius: API reference dokumentaciją, Python ir JavaScript SDK, savaitinį changelog'ą, skillus, kuriuos užsikrauna kodavimo asistentai, ir pavyzdines programėles. Nė vienas iš šių atnaujinimų nerašomas ranka — visa grandinė remiasi vienu failu, kuris veikia kaip vienintelis tiesos šaltinis.
Pavyzdys: merge proposals funkcija0:18
Kaip pavyzdys sekamas realus pakeitimas — merge proposals. Tai ElevenLabs Agents funkcija, tapusi vieša rugsėjo pabaigoje: komanda pasiūlo agento pakeitimus, juos peržiūri ir sumerge'ina, panašiai kaip pull request'ą, tik skirtą agentui. Tokia funkcija paliečia daug vietų iškart — dokumentaciją, abu SDK, release notes ir pavyzdžius. Jei kiekviena iš jų būtų atnaujinama rankomis, turinys imtų skirtis, ir dokumentacija nebeatitiktų realiai įdiegto SDK.
Endpointo apibrėžimas backend'e0:30
Viskas prasideda backend'e. Kiekvienas viešas endpointas apibrėžiamas vienoje vietoje kartu su visa informacija, kurios reikia išoriniam vartotojui: adresu, priimamais parametrais, paprastos kalbos aprašymu ir pavyzdinėmis reikšmėmis. Taip pat pridedamos dvi užuominos SDK generatoriui — grupė, kuriai metodas priklauso, ir metodo pavadinimas. Pagal nutylėjimą visi endpointai yra privatūs; inžinierius turi specialiai pažymėti endpointą kaip viešą, kad jis apskritai galėtų pasirodyti už ElevenLabs ribų, ir būtent šis jungiklis lemia, kas matoma dokumentacijoje.
Patikrinimai pull request'uose1:01
Kiekvienas pakeitimas eina per pull request'ą. Automatiniai patikrinimai sugeneruoja API aprašą du kartus — prieš pakeitimą ir po jo — ir juos palygina. Jei pakeitimas sugadintų jau veikiantį klientinį kodą, patikrinimas tai pažymi dar prieš merge'ą.
OpenAPI spec kaip tiesos šaltinis1:32
Išdiegus pakeitimą, API aprašo pati save viename OpenAPI spec faile, kuriame išvardyti visi vieši endpointai, jų įvestys ir grąžinamos reikšmės. Failas gyvai pasiekiamas adresu api.elevenlabs.io/openapi.json. Svarbi detalė — kryptis: backend'as šio failo niekam nesiunčia, visos kitos sistemos pačios jį pasiima. Taip dokumentacija ir SDK statomi iš to, kas realiai veikia produkcijoje.
Dokumentacijos generavimas kasdien2:03
Dokumentacijos repozitorija parsisiunčia spec'ą kiekvieną darbo dieną, pritaiko kelis savo override'us ir atidaro pull request'ą. Kai komandos narys jį sumerge'ina, dokumentacijos platforma perstato API reference. Merge proposals funkcija tokiu būdu gavo septynis naujus puslapius — po vieną kiekvienam endpointui — ir nė vieno iš jų niekas nerašė. Gidai, esantys šalia reference puslapių, yra išimtis: juos žmonės rašo ranka, nes paaiškinti, kada ir kodėl naudoti funkciją, reikia žmogaus.
Savaitiniai Python ir JavaScript SDK2:33
SDK išleidžiami maždaug kartą per savaitę, dažniausiai pirmadienį. Kažkas parenka vieną bendrą versijos numerį ir iš to paties spec'o sugeneruoja tiek Python, tiek JavaScript SDK; kiekvienas atkeliauja kaip pull request'as savo viešoje repozitorijoje. Merge proposals atveju tai reiškė naują metodą abiejuose SDK — mergeProposals.create — ir abu išėjo kaip versija 2.71 į PyPI ir npm. Sugeneruotas kodas niekada neredaguojamas ranka: jei reikia pataisymo, jis įrašomas į spec'ą, ir kitas release'as jį nuneša į abu SDK.
DI agentas rašo changelog'ą3:04
Tą pačią dieną vėliau DI agentas parašo savaitinį changelog'ą. Jis perskaito tris šaltinius: tos savaitės spec'o pakeitimus, naujus SDK release'us ir pull request'us, kuriuos inžinieriai pažymėjo changelog'ui. Tada parengia vieną datuotą puslapį ir atidaro pull request'ą, kurį prieš publikavimą patikrina žmogus. Merge proposals pateko į spalio 5 d. puslapį.
Skillų ir pavyzdinių programėlių atnaujinimas3:35
Šio puslapio merge'as paleidžia dar du agentus. Pirmasis perskaito naująjį changelog'ą ir atnaujina skillus — instrukcijas, kurias užsikrauna kodavimo asistentai, kad teisingai naudotų ElevenLabs su tinkamais paketų pavadinimais ir aktualiais modeliais. Prieš keisdamas skillą, agentas kiekvieną redagavimą palygina su spec'u, kad skillas nežadėtų to, ko API neturi. Sumerge'inus skillus, antrasis agentas iš jų perstato pavyzdines programėles, todėl pavyzdžiai lieka aktualūs ir kartu parodo, kaip skillai virsta veikiančia programėle.
Apibendrinimas ir nuorodos3:36
Apibendrinant: vienas kode vieną kartą apibrėžtas endpointas virsta reference puslapiais, SDK metodais, changelog įrašu, atnaujintais skillais ir veikiančiais pavyzdžiais. Kiekvienas automatinis žingsnis atidaro pull request'ą, kurį peržiūri ir sulieja žmogus — jei pradinis kodas teisingas, visa, kas eina toliau, seka paskui. Norintiems pamatyti dalis patiems siūloma atsidaryti spec'ą adresu api.elevenlabs.io/openapi.json arba pridėti skillus prie savo kodavimo asistento komanda npx skills add elevenlabs/skills; nuorodos į abu dalykus ir į tos savaitės changelog'ą pateiktos video aprašyme.
Originalas: ElevenLabs agentic engineering pipeline (ElevenLabs YouTube kanalas)