تاحالا سعی کردی واسه api با swagger مستند سازی کنی؟
روشی که بعد تماشای چندتا آموزش و خوندن مستندات رسمی OPENAPI انجام میدی، کدنویسی تو یه فایل yaml و تعریف اجزا، ریسورس و غیره همه تو همون فایله.
در نهایت صدها خط کد تو یه فایل داری که نه خوندنش راحته و پس از مدتی تغییر یا دیباگ کردنش کار ساده ای نیس.
و تنها راهی که کار و تجربه توسعه رو راحت میکنه، استفاده از SwaggerHub هستش که رایگان نیست.
این روش زیاد اکی نیس، مگه نه؟
یه راه بهتری هست اونم اینه که پوشه و فایل‌های yaml خوب نامگذاری بشن و اکسپورت بشن به یه فایل اصلی yaml.
اساساً ما همه چی رو به عنوان یک ماژول در نظر می گیریم و اکسپورت می کنیم که بعدش بتونیم ایمپورت کنیم تو یه فایل اصلی.
درواقع همه فایل‌هارو باندل می‌کنیم و یک فایل yaml به عنوان داکیونمت سواگر خواهیم داشت.
ساختاری که من پیشنهاد می کنم، ایجاد پوشه های جداگونه برای پارامتر ها، ریسورس ها، رسپانس ها و آدرس های api هستش.
در نهایت میشه همه ی فایل های yaml رو با این دستور مرج کنیم:
npx swagger-cli bundle src/openapi.yaml — outfile _build/openapi.yaml — type yaml
ابزار swagger-cli همه فایل‌های yaml رو تو یه فایل مرج میکنه که تو پوشه build_ میزارتش.
برای دیدن نتیجه کار، می تونی فایل بیلد شده رو کپی کنی و تو ادیتور Swagger پیست کنی.
سورس کد کامل رو هم گذاشتم تو گیتهابم میتونی ببینی.
