استفاده از چارچوب تجارت الکترونیک منبع باز جنگو-اسکار به عنوان مثال.
اسناد API معمولاً اولین معرفی یک توسعه دهنده برای یک پروژه است. با این حال، ممکن است قدیمی یا نادرست باشند، زیرا توسعه دهندگان در پروژه باید هر بار که کد تغییر می کند، وارد شده و اسناد را به صورت دستی به روز کنند. این نه تنها اتلاف وقت توسعه دهندگان است، بلکه به راحتی می توان آن را به طور کلی فراموش کرد. صنعت می‌گوید “اول API” – که با یک سند API شروع می‌شود – راهی برای ساخت برنامه‌ها است، اما زمانی که ضرب‌الاجل‌های محدود وجود دارد، می‌توان این رویکرد را نادیده گرفت.
AppMap یک ابزار تجزیه و تحلیل زمان اجرا پویا و رایگان است که تولید خودکار اسناد API را آسان می کند. تولید خودکار OpenAPI همچنین می تواند در سیستم CI/CD شما گنجانده شود تا از تاریخ گذشته یا نادرست بودن اسناد جلوگیری شود. روزهای نوشتن دستی اسناد API به پایان رسیده است. کد خود را بنویسید، کد خود را اجرا کنید و سند در مخزن شما ظاهر می شود.
AppMap را به Django-Oscar اضافه کنید
در قسمت اول این مجموعه، یاد گرفتید که چگونه AppMaps را برای پروژه منبع باز Django-Oscar تولید کنید. AppMaps نمایش‌های بصری کد است که به توسعه‌دهندگان اجازه می‌دهد رد درخواست‌های HTTP، فراخوانی‌های تابع و نوشته‌های پایگاه داده خود را جستجو کنند. برای نصب کتابخانه های AppMap در پایگاه کد Django-Oscar، پسوند AppMap PyCharm را اضافه کنید.
اگر از VS Code یا Jetbrains استفاده نمی کنید، یا اگر می خواهید تولید OpenAPI را در سیستم CI/CD خود بگنجانید، می توانید AppMap CLI را نصب کرده و اسناد OpenAPI را در خط فرمان ایجاد کنید.
مجموعه تست Django-Oscar را اجرا کنید
متغیر محیط خود را مطابق شکل زیر تنظیم کنید و دستور PyTest را برای اجرای مجموعه آزمایشی Django-Oscar اجرا کنید. پوشش تست گسترده است و مدتی طول می کشد تا اجرا شود، بنابراین برای مشاهده نحوه عملکرد نسل API ابتدا زیر مجموعه ای از تست ها را اجرا کنید. می‌توانید درباره تولید AppMaps از آزمایش‌های Python در AppMap Documentation اطلاعات بیشتری کسب کنید.
APPMAP_LOG_LEVEL=info pytest -svv
پس از اجرای مجموعه آزمایشی کامل، مجموعه‌ای از AppMaps با کد دقیق با تمام اطلاعات به‌روز درخواست API در داخل خواهید داشت.
روی یکی از AppMaps در نوار کناری کلیک کنید تا آن را گسترش دهید و وابستگی های داخل پروژه را بررسی کنید.
OpenAPI Spec را ایجاد کنید
اکنون که درخواست های API ما در AppMaps ما ثبت شده است، می توانید فایل مشخصات پشتیبانی شده OpenAPI v3 را از طریق PyCharm یا با استفاده از AppMap CLI ایجاد کنید. از آنجا می توانید فایل را به Postman، سایر ابزارهای مدیریت API وارد کنید یا با تیم خود به اشتراک بگذارید.
پس از تکمیل موارد آزمایش Django-Oscar، روی دکمه “Generate OpenAPI” کلیک کنید.
با این کار مولد OpenAPI باز می شود. سپس روی دکمه “Generate OpenAPI Documents” کلیک کنید و مشخصات OpenAPI شما در ویرایشگر نمایش داده می شود. این داده ها را در هر جایی که به آن نیاز دارید برای استفاده یا توزیع بعدی ذخیره کنید.
به عنوان مثال: من این مشخصات API را به عنوان یک مجموعه جدید در Postman بارگذاری کردم.
سند OpenAPI را با AppMap CLI ایجاد کنید
اگر کاربر PyCharm نیستید، یا اگر می‌خواهید تولید OpenAPI را به عنوان بخشی از فرآیند CI خود وارد کنید، می‌توانید دستور AppMap CLI را پس از اتمام آزمایش‌ها اجرا کنید تا به طور مشابه اسناد API را در یک فایل خروجی تعریف‌شده توسط کاربر خروجی بگیرید.
AppMap CLI با جاوا اسکریپت نوشته شده است که اجرای آن را در انواع پلتفرم ها آسان می کند. برای نصب AppMap CLI، باید Node.js را نصب کنید، یا می توانید باینری های از پیش ساخته شده برای @appland/appmap را در Github بگیرید. برای نصب AppMap CLI پس از نصب Node.js، دستور زیر را اجرا کنید.
npx @appland/appmap@latest openapi --output-file openapi.yml
اسناد OpenAPI را به ابزارهای دیگر وارد کنید تا راحت تر با API های خود تعامل داشته باشید، ویژگی های جدید یا به روز شده را آزمایش کنید و در نهایت اسناد OpenAPI را برای کاربران خود صادر کنید تا آنها نیز بدانند که چگونه با برنامه شما تعامل کنند.
اکنون که سند API را به صورت محلی ایجاد کرده اید، این دستور را به سیستم CI خود اضافه کنید تا اسناد OpenAPI خود را با تغییر کد به روز کنید.
می‌توانید با بررسی مستندات ما درباره سایر ویژگی‌های AppMap اطلاعات بیشتری کسب کنید یا می‌توانید به توسعه‌دهندگان انجمن Slack ما بپیوندید.
