استفاده از SmartDocs برای مستندسازی APIها

شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید . اطلاعات

SmartDocs به شما امکان می دهد API های خود را در پورتال توسعه دهنده دروپال 7 به گونه ای مستند کنید که اسناد API را کاملاً تعاملی کند. اسناد تعاملی به این معنی است که کاربران پورتال می توانند:

  • در مورد API های خود بخوانید
  • یک درخواست زنده به API خود ارسال کنید
  • مشاهده پاسخ زنده برگشتی از API

با ایجاد یک مستندات تعاملی روی API های خود، یادگیری، آزمایش و ارزیابی API های خود را برای کاربران پورتال آسان می کنید.

Edge management API یک API RESTful است که به شما امکان می دهد با استفاده از هر مشتری HTTP به خدمات API دسترسی داشته باشید. Apigee از SmartDocs برای ایجاد اسناد تعاملی برای API مدیریت Edge استفاده می کند. اسناد API را اینجا ببینید.

نمونه پورتال SmartDocs

برای استفاده از SmartDocs، باید یک پورتال Apigee Developer Services داشته باشید. برای اطلاعات بیشتر، به ایجاد پورتال توسعه‌دهنده مراجعه کنید.

از صفحه اصلی پورتال توسعه دهنده خود، روی API ها در نوار پیمایش بالا کلیک کنید تا صفحه اسناد API را مشاهده کنید.

دو API مستند در پورتال وجود دارد: Hello World و Pet Store Example.

Hello World API از هدف ساختگی OpenAPI Specification، mocktarget.yaml ایجاد شده است. برای اطلاعات بیشتر، https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi را ببینید.

Pet Store Example API از نسخه نمایشی فروشگاه حیوانات خانگی کلاسیک ایجاد شده است.

API Hello World را کاوش کنید:

  1. روی Hello World API کلیک کنید. صفحه خلاصه Hello World API نمایش داده می شود:
  2. روی View API afirmation کلیک کنید. SmartDocs برای این منبع نمایش داده می شود:
  3. روی ارسال این درخواست کلیک کنید.
  4. مشاهده پاسخ برگشتی: 
    HTTP/1.1 200 OK
Connection:
keep-alive
Content-Length:
18
Content-Type:
text/html; charset=utf-8
Date:
Tue, 21 Jun 2016 21:49:32 GMT
ETag:
W/"12-Jb9QP1bUxNSmZkxQGt5KLQ"
X-Powered-By:
Apigee
<H2>I <3 APIs</H2>
  5. برای مشاهده درخواست، روی برگه درخواست یا برای مشاهده تماس cURL مربوطه، روی برگه cURL کلیک کنید.

چگونه API های خود را با استفاده از SmartDocs مستند کنید

SmartDocs API های شما را با استفاده از یک مدل نشان می دهد که در آن مدل تمام اطلاعات مربوط به API های شما را در بر می گیرد. پورتال اطلاعات مربوط به API های شما را از مدل استخراج می کند تا صفحات مستندات موجود در پورتال را به عنوان گره های دروپال ارائه کند، که در آن هر گره دروپال با صفحه ای از اسناد در پورتال مطابقت دارد.

مراحل کلی که برای استفاده از SmartDocs دنبال می کنید عبارتند از:

  1. ماژول Drupal SmartDocs را در پورتال پیکربندی کنید .
  2. یک مدل SmartDocs ایجاد کنید .
  3. APIها را از فایل WADL، مشخصات OpenAPI (سابق Swagger) یا به صورت دستی به مدل اضافه کنید .
  4. مدل را به صورت مجموعه ای از گره های دروپال ارائه دهید . هر گره دروپال حاوی اطلاعاتی در مورد یک API است. به عنوان مثال، اگر منبعی در API شما از هر دو درخواست POST و PUT پشتیبانی می کند، SmartDocs یک گره دروپال جداگانه برای POST و PUT ایجاد می کند.
  5. گره های دروپال را منتشر کنید . پس از انتشار، کاربران پورتال شما می توانند API شما را مشاهده کرده و با آن تعامل داشته باشند.
  6. گره های دروپال را قبل یا بعد از انتشار آنها ویرایش کنید . می توانید گره های دروپال را با استفاده از ویرایشگر دروپال یا با ویرایش فایل اصلی WADL یا مشخصات OpenAPI ویرایش کنید. هنگامی که ویرایش فایل WADL یا مشخصات OpenAPI را تمام کردید، آن را به عنوان یک نسخه جدید به مدل وارد کنید، سپس تغییرات خود را رندر و منتشر کنید.
  7. TLS را فعال کنید از آنجایی که SmartDocs می تواند اعتبارنامه های احراز هویت را به عنوان بخشی از درخواست به API های شما به باطن شما ارسال کند، باید TLS را در پورتال خود فعال کنید تا از ایمن بودن آن اعتبارنامه ها اطمینان حاصل کنید. در محیط‌های تولید و آزمایش پورتال، Apigee گواهی TLS مورد نیاز برای درخواست‌های https:// را ارائه می‌کند. با این حال، قبل از اینکه با پورتال خود به صورت زنده وارد شوید، باید گواهی TLS خود را دریافت کرده و TLS را فعال کنید. برای اطلاعات بیشتر، استفاده از TLS در پورتال را ببینید.

درباره مدل ها و قالب های SmartDoc

هنگامی که یک مدل در پورتال خود ایجاد می کنید، مدل در واقع در سازمان Edge شما ذخیره می شود، نه در دروپال. یک مدل یک بلوک بزرگ از JSON با نام داخلی (مانند "my-smartdocs-api") است و ساختار یک API را تعریف می کند. پورتال شما، از طرف دیگر، مدل را در HTML ارائه می کند و یک رابط ویرایش برای مدل فراهم می کند. هر گونه به روز رسانی به API در پورتال به طور خودکار به مدل منبع بازگردانده می شود.

در سازمان ذخیره می شود

ذخیره شده در دروپال

مدل ها

قالب ها

گره های دروپال با قابلیت ویرایش

فرض کنید چندین پورتال در سازمان خود دارید (به عنوان مثال، توسعه، مرحله و تولید). در Pantheon، شما یک پورتال را از یک محیط به محیط دیگر منتقل می کنید. هر نمونه از پورتال به نظر می رسد که دارای مدل خاص خود است، اما همه آنها واقعاً به مدل منبع ارجاع می دهند. اگر API را در توسعه‌دهنده ویرایش کنید، مدل به‌روزرسانی می‌شود و تغییرات در تولید ظاهر می‌شوند. به همین ترتیب، اگر مدلی را در توسعه‌دهنده حذف کنید، منبع حذف می‌شود و دیگر در حال تولید نیست.

الگوها ظاهر و احساس SmartDocs شما را کنترل می‌کنند، و آن الگوها (که توسط Handlebars و فایل‌های CSS اداره می‌شوند) با هر نمونه پورتال ذخیره می‌شوند. بنابراین هر پورتال از نظر تئوری می تواند از یک الگوی منحصر به فرد برای هر مدل استفاده کند. با این حال، یکی از راحتی های فریم ورک رندر این است که یک قالب پیش فرض (اعم از پیش فرض Apigee یا قالبی که شما ارائه می دهید) به طور خودکار برای هر مدل اعمال می شود.

نمودار زیر ارتباط بین مدل ها و پورتال ها را نشان می دهد. فلش های سبز همگام سازی خودکار را نشان می دهد.

دستور cURL زیر تمام مدل‌های موجود در سازمان شما را فهرست می‌کند:

curl -v https://api.enterprise.apigee.com/v1/o/{your_org}/apimodels/ -u edge_org_admin@example.com

پیکربندی ماژول SmartDocs

Apigee SmartDocs را به عنوان یک ماژول سفارشی دروپال پیاده سازی کرد. برای پیکربندی ماژول SmartDocs از روش زیر استفاده کنید.

برای پیکربندی ماژول SmartDocs:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. Modules را در منوی مدیریت دروپال انتخاب کنید. لیست تمام ماژول های نصب شده دروپال ظاهر می شود.
  3. ماژول SmartDocs را فعال کنید.
  4. پیکربندی را ذخیره کنید.
  5. ماژول ها را در منوی مدیریت دروپال انتخاب کنید.
  6. SmartDocs -> Permissions را انتخاب کنید و مطمئن شوید که "Perform Administration tasks for the SmartDocs module" برای نقش "Administrator" فعال است.
  7. در منوی مدیریت دروپال ، Configuration > Dev Portal را انتخاب کنید.
  8. زمان اتصال و زمان درخواست را روی 16 ثانیه تنظیم کنید.
  9. پیکربندی را ذخیره کنید.
  10. تنظیمات URL را پیکربندی کنید:
    1. پیکربندی > جستجو و فراداده > نام مستعار URL > تنظیمات را از منوی دروپال انتخاب کنید.
    2. Maximum alias length و Maximum component length را روی 255 تنظیم کنید.
    3. علامت گذاری را گسترش دهید.
    4. برای تنظیمات براکت مجعد چپ ({) و براکت فرفری راست (}) ، بدون عمل (جایگزین نشود) را انتخاب کنید.
    5. روی Save configuration کلیک کنید.
  11. اگر پورتال توسعه دهنده شما در یک شبکه داخلی بدون دسترسی به اینترنت در معرض دید کاربران قرار می گیرد یا اگر زیرمجموعه ای از API های شما در یک شبکه خصوصی هستند، URL پروکسی SmartDocs API را به صورت زیر پیکربندی کنید:
    1. Configuration > SmartDocs را در منوی Drupal Administration انتخاب کنید.
    2. تنظیمات پیشرفته را باز کنید.
    3. فیلد URL پروکسی SmartDocs را به صورت زیر به روز کنید: < host >/smartdocs/v1/sendrequest .
      کمک درون خطی باید ارزش مورد نیاز را برای محیط شما فراهم کند. به عنوان مثال:
      https://api-us-east-1-enterprise.apigee.com/smartdocs/v1/sendrequest

      این فیلد به صورت پیش فرض https://apiconsole-prod.apigee.net/smartdocs/v1/sendrequest است
    4. روی Save configuration کلیک کنید.

ایجاد یک مدل

یک مدل حاوی تمام اطلاعات مربوط به نمایش API شما است. می توانید چندین مدل را در پورتال برای پشتیبانی از API های مختلف تعریف کنید یا همه API های خود را در یک مدل واحد گروه بندی کنید.

هر مدل یک نام داخلی منحصر به فرد را مشخص می کند که URL پایه گره های دروپال تولید شده را نیز مشخص می کند. URL هر گره دروپال به شکل زیر است:

http://<drupalBasePath>/<internalName>/apis/<httpMethod>/<resourcePath>

کجا:

  • drupalBasePath : URL پایه پورتال شما.
  • insideName : نام داخلی مدل.
  • httpMethod : روش HTTP API، مانند: دریافت، قرار دادن، ارسال یا حذف.
  • resourcePath : مسیر منبع.

به عنوان مثال، اگر نام داخلی را به عنوان "mymodel" مشخص کنید، URL برای گره دروپال تولید شده برای درخواست GET به منبعی به نام "/books" است:

http://prod-myco.devportal.apigee.com/mymodel/apis/get/books

برای ایجاد یک مدل

هنگامی که یک مدل ایجاد می کنید، در سازمان Edge شما به عنوان منبع ساختار API ذخیره می شود. برای اطلاعات بیشتر، درباره مدل‌ها و الگوهای SmartDoc را ببینید.

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. Content > SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. مدل جدید را در بالای صفحه انتخاب کنید.
  4. فیلدهای زیر را وارد کنید:
    • نام : نام مدلی که در سراسر سایت نمایش داده می شود.
    • نام داخلی : با تایپ نام ، نام داخلی نمایش داده می شود. نام داخلی مدل که باید در بین همه مدل ها منحصر به فرد باشد. نام داخلی باید فقط شامل حروف کوچک، اعداد و خط فاصله بدون فاصله باشد. برای ویرایش این نام ، Edit را انتخاب کنید.
    • توضیحات : توضیحاتی در مورد مدل.
  5. ایجاد مدل را انتخاب کنید.

پس از ایجاد مدل، به صفحه مدل هدایت می شوید. از آنجا، می توانید از پنجره کشویی عملیات bx برای موارد زیر استفاده کنید:

  • یک فایل WADL را وارد کنید که API شما را توصیف می کند یا URL یک مشخصات OpenAPI را که API شما را توصیف می کند، مشخص کنید.
  • Revision را به مدل اضافه کنید
  • تنظیمات مدل، از جمله شیوه نامه های استفاده شده توسط مدل را تغییر دهید.
  • مدل را به یک فایل صادر کنید .
  • مدل را حذف کنید

افزودن API به یک مدل

شما می توانید API را به یک مدل اضافه کنید:

  • وارد کردن یک فایل WADL حاوی تعریف API
  • وارد کردن مشخصات OpenAPI (OpenAPI 2.0 یا 1.2)
  • ایجاد منابع و روش ها به صورت دستی

همچنین می توانید یک فایل JSON SmartDocs را به یک مدل وارد کنید. این فایل معمولاً با صادرات یک مدل موجود، ویرایش فایل و سپس وارد کردن به‌روزرسانی‌ها ایجاد می‌شود. برای اطلاعات بیشتر به « صادر کردن و وارد کردن مدل » در زیر مراجعه کنید.

ویدئو: برای یادگیری نحوه افزودن API به مدل SmartDocs با وارد کردن مشخصات OpenAPI، یک ویدیوی کوتاه تماشا کنید.

یک WADL وارد کنید

پس از ایجاد موفقیت آمیز یک مدل، یک فایل WADL را وارد کنید که API شما را توصیف می کند. هر بار که یک فایل WADL را وارد می کنید، به طور خودکار یک نسخه جدید از مدل ایجاد می کنید.

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. Content > SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. مدلی را که می خواهید به روز کنید انتخاب کنید.
  4. در بخش عملیات ، واردات را انتخاب کنید.
  5. WADL را در منوی انتخاب فرمت در صفحه واردات SmartDocs انتخاب کنید.
  6. فایل یا URL را در منوی بارگذاری نوع آپلود انتخاب کنید.
    1. اگر فایل را انتخاب کنید، به فایل WADL بروید.
    2. اگر URL را انتخاب کردید، آدرس فایل WADL را مشخص کنید.
  7. برای وارد کردن آن به مدل روی Import کلیک کنید. اکنون می توانید مدل را رندر کنید.
  8. شما به صفحه اطلاعات مدل هدایت می شوید که اکنون می توانید مدل را رندر کنید.

یک مشخصات OpenAPI را وارد کنید

پس از ایجاد موفقیت آمیز یک مدل، می توانید مشخصات OpenAPI (Swagger سابق) را وارد کنید. Edge از OpenAPI نسخه 1.2 و 2.0 پشتیبانی می کند.

OpenAPI از فایل های حاوی اشیاء JSON برای توصیف یک API استفاده می کند. هر بار که یک OpenAPI Specification را وارد می کنید، به طور خودکار یک نسخه جدید از مدل ایجاد می کنید.

برای وارد کردن مشخصات OpenAPI:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. Content > SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. مدلی را که می خواهید به روز کنید انتخاب کنید.
  4. در بخش عملیات ، واردات را انتخاب کنید.
  5. Swagger JSON یا Swagger YAML را در منوی کشویی Choose Format در صفحه واردات SmartDocs انتخاب کنید.
  6. فایل یا URL را در منوی بازشو نوع آپلود انتخاب کنید (شما باید URL را برای OpenAPI 1.2 انتخاب کنید).
    1. اگر فایل را انتخاب کنید، به مشخصات OpenAPI بروید.
    2. اگر URL را انتخاب کردید، URL مشخصات OpenAPI را مشخص کنید.
  7. برای وارد کردن آن به مدل روی Import کلیک کنید.
  8. شما به صفحه اطلاعات مدل هدایت می شوید که اکنون می توانید مدل را رندر کنید.

منابع و روش ها را به صورت دستی ایجاد کنید

اگر فایل WADL یا مشخصات OpenAPI ندارید که نمایانگر API شما باشد، می‌توانید به صورت دستی API را به مدل خود اضافه کنید. همچنین، اگر از یک فایل WADL یا مشخصات OpenAPI برای ایجاد مدل خود استفاده می کنید، می توانید از این روش برای ویرایش API های خود، از جمله افزودن API های جدید، پس از وارد کردن استفاده کنید.

برای افزودن دستی یک API:

  1. یک ویرایش جدید از مدل ایجاد کنید.

    هنگامی که ویرایش را ایجاد می‌کنید، مسیر اصلی همه APIها را در مدل مشخص می‌کنید، به این معنی که همه APIهای یک مدل مسیر پایه یکسانی دارند. برای مثال مسیر پایه را به صورت زیر مشخص کنید:

    https://myCompany.com/v1

    وقتی منابعی را به مدل اضافه می کنید، مسیر پایه را گسترش می دهند.
  2. یک یا چند منبع را برای مدل تعریف کنید. مسیر منبع با مسیر اصلی ویرایش مدل ترکیب می شود تا URL کامل منبع را مشخص کند. به عنوان مثال، اگر منبع شما مسیر "/login" را تعریف کند، URL کامل منبع به صورت زیر است:

    https://myCompany.com/v1/login
  3. برای هر منبع یک یا چند روش تعریف کنید. یک متد فعل HTTP را مشخص می کند که می تواند در یک منبع فراخوانی شود. به عنوان مثال، برای منبع "/login"، شما از POST برای ورود به سیستم و DELETE برای خروج از سیستم پشتیبانی می کنید. این منبع از سایر افعال HTTP مانند PUT یا GET پشتیبانی نمی کند. بنابراین، دو روش برای منبع تعریف کنید، یکی برای POST و دیگری برای DELETE.

    این روش از URL منبع از منبع اصلی خود استفاده می کند. بنابراین، همه روش‌ها با URL یکسان تحت یک منبع واحد در SmartDocs تعریف می‌شوند.

به عنوان یک قاعده کلی:

  • یک مدل SmartDocs متفاوت برای هر مسیر پایه منحصر به فرد در API خود ایجاد کنید.
  • یک منبع SmartDocs متفاوت برای هر منبع منحصر به فرد در API خود تعریف کنید.
  • برای هر فعل HTTP که توسط یک منبع پشتیبانی می شود، یک روش SmartDocs متفاوت تعریف کنید.

ایجاد یک ویرایش جدید از یک مدل

شما فقط می توانید یک منبع را به یک نسخه موجود از یک مدل اضافه کنید. اگر مدل قبلاً یک ویرایش دارد، می توانید منبع خود را اضافه کنید. اگر مدل جدید است و هیچ ویرایشی ندارد، یک ویرایش جدید ایجاد کنید.

برای ایجاد یک ویرایش جدید از یک مدل:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. Content > SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. برای مدلی که می خواهید به روز کنید، Add Revision را در قسمت Operations انتخاب کنید.
  4. در صفحه Add API Revision اطلاعات زیر را وارد کنید:
    • نام نمایشی : نام ویرایش همانطور که در پورتال ظاهر می شود.
    • شناسه نسخه : یک شناسه کوتاه برای بازبینی.
    • توضیحات : شرحی از بازبینی.
    • URL پایه : URL پایه همه APIها در بازبینی مدل. یک مدل می تواند از URL های پایه متفاوت برای هر ویرایش استفاده کند. به عنوان مثال، شما یک نشانگر نسخه را در URL اصلی قرار می دهید. برای اولین ویرایش مدل، URL پایه این است:
      https://myCompany.com/v1
      برای ویرایش بعدی، URL پایه می تواند این باشد:
      https://myCompany.com/v2
  5. Add Revision را انتخاب کنید. شما به صفحه بازبینی مدل هدایت می شوید. اکنون می توانید منابع را روی مدل تعریف کنید.

تعریف یک منبع

یک منبع URL کامل یک API را مشخص می کند. هنگام تعریف یک منبع، مسیر منبع را مشخص می‌کنید که با URL اصلی در ویرایش مدل ترکیب می‌شود تا URL کامل منبع ایجاد شود.

برای تعریف یک منبع:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. Content > SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. برای مدلی که می‌خواهید به‌روزرسانی کنید، در بخش Operations ، API Revisions را انتخاب کنید تا همه نسخه‌های یک مدل را مشاهده کنید.
  4. یک نسخه را برای ویرایش انتخاب کنید.
  5. در صفحه ویرایش، از منوی کشویی گزینه Add Resource را انتخاب کنید.
  6. در صفحه افزودن منبع ، اطلاعات زیر را وارد کنید:
    • نمایش نام : نام منبع.
    • مسیر : مسیر منبع که با "/" شروع می شود. مقدار Path با URL اصلی نسخه ویرایش مدل ترکیب می شود تا URL کامل منبع ایجاد شود.
    • توضیحات : شرحی از منبع.
    • پارامترها : به صورت اختیاری شی JSON را وارد کنید که هر پارامتر را در منبع تعریف می کند. این پارامترها در زیر توضیح داده شده است.
  7. افزودن منبع را انتخاب کنید. شما به صفحه مدل هدایت می شوید. اکنون می توانید روش هایی را روی منبع تعریف کنید.

به صورت اختیاری، می توانید پارامترهایی مانند پارامترهای الگو، پرس و جو و هدر را به منبع اضافه کنید. تمام پارامترهای منبع با هر روشی که روی آن منبع تعریف شده است به ارث می رسد. بنابراین، اگر یک پارامتر پرس و جو را روی منبع تعریف کنید، تمام متدهای اضافه شده به آن منبع باید از آن پارامتر کوئری پشتیبانی کنند.

همچنین، می‌توانید پارامترهای یک متد را تعریف کنید. به عنوان مثال، یک متد POST ممکن است از پارامترهای پرس و جو پشتیبانی کند که توسط روش DELETE پشتیبانی نمی شوند. بنابراین، هنگامی که متد را تعریف می کنید، هر پارامتری را که در زیر توضیح داده شده است، اضافه کنید.

تصویر زیر یک صفحه SmartDocs موجود برای Apigee Approve یا Revoke Developer App API را با هر نوع پارامتر برجسته شده نشان می دهد:

هر نوع پارامتر توسط یک شی JSON تعریف می شود:

تایپ کنید

شی JSON

یادداشت ها

الگو

{
"dataType": "string",
"defaultValue": "",
"description": "نام سازمان."،
"name": "org_name",
«لازم»: درست است،
"type": "TEMPLATE"
}

پارامترهای الگو همیشه مورد نیاز هستند، بنابراین مورد نیاز را روی true تنظیم کنید و مقدار defaultValue را حذف کنید.

هنگامی که کاربر روی URL در صفحه SmartDocs می‌چرخد، مقدار توضیحات در یک پنجره بازشو ظاهر می‌شود.

پرس و جو

{
"dataType": "string",
"defaultValue": "",
"description": "مکان."،
"name": "w",
«لازم»: درست است،
"type": "QUERY"
}

پارامترهای پرس و جوی مورد نیاز همچنان می توانند یک مقدار پیش فرض را تعیین کنند، اما اغلب این کار را نمی کنند.

برای پارامترهای پرس و جوی اختیاری، مورد نیاز را روی false تنظیم کنید و مقداری را به defaultValue مشخص کنید.

سربرگ

{
"dataType": "string",
"defaultValue": "application/json",
"description": "مشخص به عنوان <code>application/json</code>."،
"name": "Content-Type",
«لازم»: درست است،
"type": "HEADER"
}

توجه کنید که چگونه می توانید از تگ های HTML در توضیحات استفاده کنید.

یک پارامتر الگو یک متغیر را در مسیر منبع تعریف می کند. به عنوان مثال، شما دو پارامتر الگو را روی منبع تعریف می کنید. توجه کنید که چگونه هر تعریف پارامتر در آرایه پارامتر با کاما از هم جدا می شود:

[
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the organization name.",
  "name": "org_name",
  "required": true,
  "type": "TEMPLATE"
 },
 {
  "dataType": "string",
  "defaultValue": "",
  "description": "Mention the user email.",
  "name": "developer_email",
  "required": true,
  "type": "TEMPLATE"
 }
]

سپس می توانید از پارامترهای الگو در تعریف مسیر منبع که در "{}" محصور شده است استفاده کنید. برای مثال مسیر را به صورت زیر تنظیم کنید:

/login/{org_name}/{developer_email}

در صفحه SmartDocs API، کاربر باید URL را ویرایش کند تا قبل از ارسال درخواست ، org_name و قسمت developer_email URL را مشخص کند.

تعریف یک روش

برای هر منبع یک یا چند روش تعریف کنید. تعریف متد یک فعل HTTP را مشخص می کند که می تواند در منبع فراخوانی شود. یک منبع می تواند یک متد تعریف شده روی آن یا چندین روش داشته باشد.

به عنوان بخشی از تعریف متد، هر پارامتری که توسط متد استفاده می شود، از جمله پارامترهای پرس و جو و هدر را مشخص کنید. برای اطلاعات در مورد افزودن پارامترها به یک روش، به توضیحات بالا مراجعه کنید.

تصویر زیر یک صفحه SmartDocs موجود برای Apigee Create Developer API را نشان می‌دهد که هر قسمت از صفحه با مقدار مربوطه ای که هنگام تعریف یک روش تعیین می‌کنید برجسته شده است:

تصویر بعدی همان صفحه را نشان می‌دهد، اما توضیحات بدنه درخواست انتخاب شده است:

برای تعریف روش:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. Content > SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. برای مدلی که می‌خواهید به‌روزرسانی کنید، در بخش Operations ، API Revisions را انتخاب کنید تا همه نسخه‌های یک مدل را مشاهده کنید.
  4. یک نسخه را برای ویرایش انتخاب کنید.
  5. در صفحه ویرایش، گزینه Add Method را از منوی کشویی برای یکی از منابع انتخاب کنید.
  6. در صفحه ویرایش روش ، اطلاعات زیر را وارد کنید:
    • نمایش نام : نام API، که همچنین عنوان صفحه دروپال برای API می شود.
    • توضیحات : API را توضیح دهید.
    • فعل روش : نوع فعل HTTP.
    • طرح‌های امنیتی : در صورت وجود، حالت احراز هویت را برای روش مشخص کنید. برای اطلاعات بیشتر، پیکربندی نوع احراز هویت SmartDocs را ببینید.
    • نوع محتوا : نوع محتوای درخواست و پاسخ. بخش زیر را در مورد پیکربندی روش های مختلف احراز هویت ببینید.
    • پارامترها : (اختیاری) هر پرس و جو یا پارامتر سرصفحه برای روش. برای اطلاعات بیشتر برای افزودن پارامتر به یک منبع به توضیحات بالا مراجعه کنید.
    • درخواست بدنه مستندات : (اختیاری) بدن درخواست را توصیف کنید. متدهای POST و PUT بدنه درخواست را می گیرند. می توانید از این ناحیه برای توصیف آن استفاده کنید. اگر این مقدار را حذف کنید، پیوند توضیحات در قسمت درخواست بدنه از صفحه SmartDocs ایجاد شده حذف می شود.
    • مثال بدنه درخواست : (اختیاری) نمونه ای از بدنه درخواست را نشان دهید، معمولاً به عنوان یک شی JSON یا به عنوان XML. برای افعال POST و PUT، Request Body Example به عنوان بخشی از هر درخواست ارسال می شود. کاربران صفحه SmartDocs این مثال را قبل از ارسال درخواست به API ویرایش می کنند. اگر این مقدار را حذف کنید، پیوند Value زیر Request Body از صفحه SmartDocs ایجاد شده حذف می‌شود.
    • برچسب‌ها : آرایه‌ای از برچسب‌های مرتبط با API. SmartDocs از برچسب ها برای گروه بندی API های مشابه با هم استفاده می کند. به عنوان مثال، ممکن است برچسب "Statistics" را برای همه APIهای مربوط به آمار اعمال کنید. می توانید API ها را از منابع مختلف تحت یک تگ گروه بندی کنید. اگر همه آنها از یک برچسب استفاده کنند.
  7. افزودن روش را انتخاب کنید. شما به صفحه مدل هدایت می شوید. اکنون می توانید روش خود را رندر و منتشر کنید.

ارائه یک مدل

بعد از اینکه API ها را به یک مدل اضافه کردید، می توانید مدل را رندر کنید. رندر توضیح مدل از API را به گره های دروپال تبدیل می کند. وقتی رندر کامل شد، برای هر API یک گره دروپال خواهید داشت که هر گره دروپال با یک صفحه HTML مطابقت دارد.

می‌توانید کل مدل را به‌طور هم‌زمان رندر کنید یا APIهای جداگانه را برای رندر انتخاب کنید.

برای ارائه یک مدل:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. Content > SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. برای مدلی که می خواهید رندر کنید، API Revisions را در قسمت Operations انتخاب کنید.
  4. نسخه ای را که می خواهید ارائه کنید انتخاب کنید. فقط می‌توانید گره‌ها را از یک نسخه نسخه‌ای از مدل رندر کنید.
  5. روش های رندر را انتخاب کنید.
  6. Render Nodes را از منوی گزینه Update انتخاب کنید.
  7. روی Update کلیک کنید.
  8. یک صفحه بارگیری برای مشاهده پیشرفت گره های شما که رندر می شوند ظاهر می شود.
    پس از رندر شدن گره ها، شناسه گره دروپال برای هر API در زیر ستون Node Association مدل ظاهر می شود. برای مشاهده گره رندر شده روی پیوند در ستون Node Association کلیک کنید.

به جای انتخاب Render Nodes، می توانید Render را انتخاب کنید و نودها را برای رندر منتشر کنید و بلافاصله API ها را به عنوان گره دروپال منتشر کنید.

انتشار گره ها

یک گره تا زمانی که منتشر نشود برای کاربران پورتال قابل مشاهده نیست. شما می توانید به صورت اختیاری انتخاب کنید که گره ها را در طول فرآیند رندر منتشر کنید. اگر تصمیم گرفتید که گره ها را منتشر نکنید، پس از اتمام رندر باید آنها را به صورت دستی منتشر کنید.

برای انتشار یک گره:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. Content > SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. برای مدلی که می خواهید منتشر کنید، API Revisions را در قسمت Operations انتخاب کنید.
  4. نسخه ای را که می خواهید منتشر کنید انتخاب کنید. شما فقط می‌توانید گره‌ها را از یک ویرایش واحد منتشر کنید.
  5. روش های انتشار را انتخاب کنید.
  6. گره های موجود در ویرایش را برای انتشار انتخاب کنید.
  7. Publish Nodes را از منوی گزینه Update انتخاب کنید.
  8. روی Update کلیک کنید.
  9. با انتخاب شناسه گره زیر ستون Node Association به گره بروید.

به طور پیش فرض، URL دروپال به یک گره API منتشر شده به این شکل است: http://< drupalBasePath >/< interiorName >/apis/< httpMethod >/< resourcePath > . برای کنترل فرم URL از روش زیر استفاده کنید:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. پیکربندی > جستجو و فراداده > نام مستعار URL > الگوها را در منوی مدیریت دروپال انتخاب کنید.
  3. در قسمت Pattern for all SmartDocs Method مسیرهای نحوه تولید مسیر را مشخص کنید.
  4. Save configuration را انتخاب کنید.

به دلیل ذخیره در پورتال، ممکن است صفحات مدل خود را بلافاصله پس از انتشار مشاهده نکنید. در صورت لزوم، با استفاده از روش زیر می توانید کش HTML SmartDocs را به صورت دستی پاک کنید:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. Configuration > SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. روی بازسازی حافظه پنهان مدل SmartDocs کلیک کنید.

لغو انتشار یک گره

شما می توانید هر زمان که بخواهید انتشار یک گره منتشر شده را لغو کنید. لغو انتشار یک گره آن را برای کاربران پورتال نامرئی می کند.

برای لغو انتشار یک گره:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. Content > SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. برای مدلی که می‌خواهید انتشار آن را لغو کنید، API Revisions را در قسمت Operations انتخاب کنید.
  4. ویرایش مدل گره‌ای را که می‌خواهید لغو انتشار کنید، انتخاب کنید.
  5. گره های موجود در ویرایش را برای لغو انتشار انتخاب کنید.
  6. Unpublish Nodes را از منوی گزینه Update انتخاب کنید.
  7. روی Update کلیک کنید.

مشاهده بازبینی یک مدل

شما یک نسخه جدید از یک مدل را با وارد کردن یک فایل WADL جدید یا مشخصات OpenAPI به یک مدل موجود یا با ایجاد دستی یک ویرایش جدید ایجاد می‌کنید. پس از ایجاد نسخه جدید، می توانید نسخه را رندر و منتشر کنید که جایگزین گره های دروپال منتشر شده فعلی می شود.

می‌توانید همزمان گره‌ها را از چندین ویرایش رندر و منتشر کنید. به این معنی که اگر پنج نسخه از یک مدل دارید، می‌توانید گره‌ها را از یک یا همه نسخه‌ها منتشر کنید. با این حال، انتشار یک API در یک مدل که همان گره منتشر شده از یک مدل دیگر است، نسخه قدیمی‌تر API را لغو انتشار می‌کند و آن را با نسخه‌ای از آخرین API منتشر شده جایگزین می‌کند.

برای مشاهده بازبینی یک مدل:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. Content > SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. برای مدلی که می خواهید به روز کنید، API Revisions را در قسمت Operations انتخاب کنید.
  4. ویرایش مدلی را که می خواهید مشاهده کنید انتخاب کنید.
  5. همانطور که در بالا توضیح داده شد، گره ها را رندر و منتشر کنید.

در حال ویرایش یک گره

پس از رندر کردن یک گره، می توانید آن را با استفاده از ویرایشگر دروپال ویرایش کنید. به عنوان مثال، می توانید فعل HTTP و توضیحات یک API را ویرایش کنید یا یک پرس و جو یا پارامتر هدر جدید به API اضافه کنید. می توانید گره های ایجاد شده از یک فایل WADL یا مشخصات OpenAPI یا گره هایی که به صورت دستی ایجاد شده اند را ویرایش کنید.

همچنین می توانید فایل اصلی WADL یا مشخصات OpenAPI را ویرایش کنید. پس از اتمام ویرایش، فایل WADL یا OpenAPI Specification را به عنوان یک ویرایش جدید دوباره به مدل وارد کنید، سپس تغییرات خود را همانطور که در بالا توضیح داده شد رندر و منتشر کنید.

برای ویرایش گره با استفاده از ویرایشگر دروپال:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. به گره دروپال مربوط به اسناد API که می خواهید ویرایش کنید، بروید.
  3. برای استفاده از ویرایشگر دروپال ، Edit را انتخاب کنید.
  4. پس از تکمیل ویرایش‌هایتان، روش به‌روزرسانی را انتخاب کنید.

همچنین، می‌توانید گره را از مدل SmartDocs ویرایش کنید:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. انتخاب کنید Content > SmartDocs در منوی مدیریت دروپال.
  3. برای مدلی که می خواهید به روز کنید، API Revisions را در قسمت Operations انتخاب کنید.
  4. نسخه مدلی را که می خواهید منتشر کنید انتخاب کنید.
  5. روش ویرایش را در منوی عملیات برای روشی که می خواهید ویرایش کنید، انتخاب کنید.

برای حذف یک گره:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. انتخاب کنید Content > SmartDocs در منوی مدیریت دروپال.
  3. برای مدلی که می خواهید به روز کنید، API Revisions را در قسمت Operations انتخاب کنید.
  4. نسخه مدلی را که می خواهید منتشر کنید انتخاب کنید.
  5. روش حذف را در منوی عملیات مربوط به روش انتخاب کنید.
    احتیاط: حذف گره همچنین API را از مدل حذف می کند. اگر فقط می خواهید API را لغو انتشار کنید تا از دید کاربران پورتال پنهان شود، اما نمی خواهید آن را از مدل حذف کنید، باید همانطور که در بالا توضیح داده شد، گره را لغو انتشار کنید.

پورتال دارای یک گزارش داخلی است که اطلاعات مربوط به هر گره ارائه شده توسط یک مدل SmartDocs را نشان می دهد که دیگر به روش های معتبر مدل اشاره نمی کند. با انتخاب گزارش ها در منوی دروپال و سپس انتخاب گزارشی به نام وضعیت گره SmartDocs به گزارش دسترسی پیدا کنید.

صادرات و واردات مدل

SmartDocs به شما امکان می دهد یک مدل موجود را به یک فایل صادر کنید. برای مثال، ممکن است یک محیط تولید و صحنه را تعریف کنید. سپس تمام ویرایش‌های SmartDocs خود را در محیط صحنه‌سازی انجام می‌دهید. وقتی آماده انتشار APIهای خود هستید، مدل مرحله‌بندی را صادر کرده و آن را به مدل تولید وارد می‌کنید.

وارد کردن یک مدل یک تجدید نظر جدید در مدل ایجاد می کند. SmartDocs تلاش می کند API های موجود در مدل را با API های وارد شده مطابقت دهد. اگر SmartDocs مطابقت را تشخیص دهد، وارد کردن گره دروپال مربوط به API موجود را به روز می کند. اگر SmartDocs مطابقت را تشخیص ندهد، وارد کردن یک گره دروپال جدید برای API ایجاد می‌کند.

به عنوان مثال، شما یک API POST دارید که مربوط به گره دروپال با شناسه 91 است. سپس یک مدل را وارد می‌کنید و SmartDocs مطابقت یک API POST در مدل وارد شده را به API موجود POST تشخیص می‌دهد. هر گونه به روز رسانی در POST API سپس گره 91 دروپال را به روز کنید. اگر SmartDocs مطابقت را تشخیص ندهد، یک گره دروپال جدید با شناسه جدید ایجاد می کند.

دروپال مطابقت را با استفاده از ویژگی های زیر در API انجام می دهد:

  • interiorName : نام مدل داخلی.
  • httpMethod : روش HTTP API، مانند: GET، PUT، POST یا DELETE.
  • resourcePath : مسیر منبع.
  • پارامترهای پرس و جو : هر گونه پارامتر پرس و جو که توسط API استفاده می شود.

اگر هر چهار ویژگی یک API وارد شده با API موجود در مدل مطابقت داشته باشد، SmartDocs گره دروپال موجود را به روز می کند.

مدل صادر شده توسط یک شی JSON با ورودی هایی برای منابع و روش ها نشان داده می شود. این بدان معناست که شما می توانید مدل صادر شده را برای اصلاح یک منبع یا روش ویرایش کنید و سپس مدل را دوباره وارد کنید. اگر شی JSON را ویرایش می کنید، فیلدهای زیر را تغییر ندهید:

  • شماره تجدیدنظر
  • createTime
  • modifiedTime
  • apiRevisionId
  • شناسه منبع

برای صادرات یک مدل:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. Content > SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. برای مدلی که می‌خواهید صادر کنید، Export را در قسمت Operations انتخاب کنید.
  4. نوع فایل صادراتی را به عنوان SmartDocs JSON انتخاب کنید.
  5. روی صادرات کلیک کنید.
  6. از شما خواسته می شود که فایل را روی دیسک ذخیره کنید یا آن را در یک ویرایشگر باز کنید.

برای وارد کردن مدل:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. Content > SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. برای مدلی که می خواهید وارد کنید، Import را در قسمت عملیات انتخاب کنید.
  4. SmartDocs JSON را در منوی انتخاب فرمت انتخاب کنید.
  5. فایل یا URL را در قسمت انتخاب کنید نوع آپلود:
    1. اگر فایل را انتخاب کنید، به فایل JSON بروید.
    2. اگر URL را انتخاب کردید، URL فایل JSON SmartDocs را مشخص کنید.
  6. برای وارد کردن آن به مدل روی Import کلیک کنید.
  7. شما به صفحه اطلاعات مدل هدایت می شوید که اکنون می توانید مدل را رندر کنید. توجه داشته باشید که واردات یک تجدید نظر جدید در مدل ایجاد می کند.
  8. گره ها را رندر و منتشر کنید.

در حال ویرایش قالب SmartDocs

الگوی SmartDocs نحوه نمایش گره های دروپال شما بر روی صفحه را مشخص می کند. هر مدل SmartDocs می‌تواند از همان الگوی پیش‌فرض استفاده کند یا می‌توانید الگوی مورد استفاده برای یک مدل را به صورت دستی سفارشی کنید.

قالب SmartDocs شامل یک فایل الگو است که به صورت فایل Handlebars .hbr، فایل‌های CSS و فایل‌های جاوا اسکریپت کدگذاری شده است. با Handlebars، بیشتر محتوا با استفاده از عبارات فرمان جاسازی شده، مانند &123;&123;body}} متغیر محور است. فهرستی از عبارات Handlebar موجود در یک نظر در بالای فایل ارائه شده است. برای اطلاعات در مورد استفاده از Handlebars برای سفارشی کردن الگوهای خود، http://handlebarsjs.com را ببینید.

بخش‌های زیر نحوه آپلود یک فایل قالب SmartDocs سفارشی را برای استفاده توسط همه مدل‌های جدید یا برای زمانی که APIهای جدید را به یک مدل موجود وارد می‌کنید، نحوه بازیابی فایل الگوی پیش‌فرض SmartDocs و نحوه تغییر الگوی SmartDocs برای مدل فردی

بارگذاری یک فایل قالب سفارشی SmartDocs

شما می توانید یک پرونده الگوی SmartDocs سفارشی ، به عنوان یک پرونده Handlebars .hbr بارگذاری کنید تا هنگام ایجاد مدل های جدید یا وارد کردن API های جدید به یک مدل موجود ، به عنوان الگوی پیش فرض استفاده کنید.

اگر می خواهید در هنگام ایجاد فایل الگوی SmartDocs سفارشی خود از پرونده الگوی پیش فرض SmartDocs به عنوان نقطه شروع استفاده کنید ، می توانید یک نسخه را از طریق: profiles/apigee/modules/custom/devconnect/smartdocs/templates/smartdocs.hbr بارگیری کنید.

برای بارگذاری یک پرونده الگوی SmartDocs سفارشی:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. پیکربندی> SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. قسمت تنظیمات پیشرفته صفحه را گسترش دهید.
  4. در زیر الگوی روش سفارشی آپلود ، روی انتخاب پرونده کلیک کنید و به پرونده Handlebars .hbr بروید.
  5. روی آپلود کلیک کنید.
  6. روی Save configuration کلیک کنید.

بازگرداندن پرونده الگوی پیش فرض SmartDocs

می توانید پرونده الگوی پیش فرض SmartDocs را بازیابی کنید. پس از ترمیم ، از پرونده الگوی پیش فرض SmartDocs هنگام ایجاد مدل های جدید یا وارد کردن API های جدید به یک مدل موجود استفاده می شود.

برای بازیابی پرونده الگوی پیش فرض SmartDocs:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. پیکربندی> SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. قسمت تنظیمات پیشرفته صفحه را گسترش دهید.
  4. در زیر الگوی روش سفارشی آپلود ، روی حذف مجاورت پرونده الگوی SmartDocs سفارشی کلیک کنید.
  5. روی Save configuration کلیک کنید.

اصلاح الگوی SmartDocs برای یک مدل فردی

می توانید الگوی مورد استفاده برای یک مدل جداگانه را تغییر دهید.

برای اصلاح الگوی برای یک مدل غلیظ:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. محتوا> SmartDocs را در منوی مدیریت دروپال انتخاب کنید.
  3. برای مدلی که می خواهید ویرایش کنید ، تنظیمات را تحت عملیات انتخاب کنید.
  4. در منطقه الگوی روش ، الگوی را طبق نیاز ویرایش کنید.
  5. روی Save Template کلیک کنید.
  6. به یک گره دروپال مرور کنید. باید تغییرات الگوی خود را در صفحه مشاهده کنید.

پیکربندی نوع احراز هویت SmartDocs

API های تعریف شده در SmartDocs یا می توانند باز باشند ، به این معنی که هیچ اعتبار احراز هویت برای دسترسی به آنها یا امنیت لازم نیست. یک API امن مستلزم آن است که هنگام برقراری تماس با API ، اعتبارنامه را منتقل کنید.

برای یک API ایمن ، SmartDocs از انواع احراز هویت زیر پشتیبانی می کند:

  • احراز هویت اساسی - اعتبار اعتبارنامه اصلی را به عنوان یک جفت نام کاربری و رمز عبور منتقل کنید. اگر شما از استفاده از OAuth به عنوان نوع اعتبار استفاده نمی کنید ، API به استفاده از تأیید اعتبار اولیه پیش فرض می کند.
  • OAUTH 2.0 - یک ارائه دهنده خدمات شخص ثالث اعتبارنامه کاربر را تأیید می کند ، تضمین می کند که کاربر مجوز API را داشته باشد ، و سپس یک نشانه دسترسی صادر می کند. هنگامی که درخواست SmartDocs را به یک API محافظت شده می کنید ، SmartDocs درخواست را می سازد و آن را به ارائه دهنده خدمات ارسال می کند. ارائه دهنده خدمات سپس نشانه را تأیید می کند و تضمین می کند که منقضی نشده است.
  • توکن سفارشی - یک مقدار توکن را به عنوان یک هدر یا پارامتر پرس و جو به هر درخواست منتقل کنید.

برای هر نوع احراز هویت ، شما یک طرح امنیتی ایجاد می کنید که ویژگی های احراز هویت را تعریف می کند. به عنوان مثال ، برای احراز هویت توکن سفارشی ، طرح امنیتی نحوه تصویب نشانه (هدر ، پرس و جو پارام ، بدنه پارام) و نام توکن را تعریف می کند.

یک طرح امنیتی با تجدید نظر خاص از یک مدل همراه است. بنابراین ، اگر تجدید نظر جدیدی از یک مدل ایجاد می کنید ، باید طرح های امنیتی را برای آن تجدید نظر دوباره تعریف کنید

در یک فایل WADL ، شما مشخص می کنید که آیا یک API با استفاده از برچسب <apigee: Authentication> Apigee ، همانطور که در زیر آمده است ، به تأیید اعتبار نیاز دارد:

<method id="statusespublic_timeline" name="GET" apigee:displayName="PublicTimeline">
    ...
    <apigee:authentication required="true"/>
</method>

اگر API باز است ، ویژگی مورد نیاز را روی False تنظیم کنید.

توجه کنید که شما نمی توانید نوع تأیید اعتبار را در پرونده WADL مشخص کنید. شما این کار را با ویرایش گره در دروپال انجام می دهید. برای اطلاعات بیشتر در مورد پرونده های WADL ، به مرجع WADL مراجعه کنید.

در صفحه API در دروپال ، SmartDocs دکمه زیر را اضافه می کند تا به کاربران اجازه دهد اعتبارنامه اصلی خود را مشخص کنند:

اگر گره را برای تنظیم نوع احراز هویت در OAuth ویرایش می کنید ، SmartDocs دکمه زیر را به صفحه اضافه می کند:

برای نشانه های سفارشی ، SmartDocs اضافه می کند:

پیکربندی احراز هویت اساسی

اگر از API خود از تأیید اعتبار اصلی استفاده می کنید ، فقط باید برچسب <apigee: retuentication> را در پرونده WADL که برای ایجاد مدل استفاده می کنید ، مشخص کنید.

برای اعمال احراز هویت اساسی در روشهای ایجاد شده از یک منبع غیر از پرونده WADL:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. انتخاب کنید محتوا> SmartDocs در منوی مدیریت دروپال.
  3. برای مدل مورد نظر ، نسخه های API را تحت عملیات انتخاب کنید.
  4. برای تجدید نظر در مدل که می خواهید ویرایش کنید ، تنظیمات امنیتی را تحت عملیات انتخاب کنید.
  5. Add Security Security را انتخاب کنید.
  6. نام طرح امنیتی را مشخص کنید.
  7. BASIC را به عنوان نوع انتخاب کنید.
  8. ارسال را انتخاب کنید.
  9. برای هر روش در مدل ، روش را ویرایش کنید تا طرح امنیتی خود را بر روی طرح اساسی خود تنظیم کنید.
    1. انتخاب کنید محتوا> SmartDocs در منوی مدیریت دروپال.
    2. برای مدل مورد نظر ، نسخه های API را تحت عملیات انتخاب کنید.
    3. برای تجدید نظر در مدل که می خواهید ویرایش کنید ، جزئیات Revision را تحت عملیات انتخاب کنید.
    4. روش ویرایش را برای API که می خواهید ویرایش کنید انتخاب کنید.
    5. طرح امنیتی را برای API انتخاب کنید.
    6. API را ذخیره کنید .

پیکربندی احراز هویت OAUTH 2.0

می توانید به جای پیش فرض احراز هویت اساسی ، یک مدل را برای استفاده از OAuth 2.0 در SmartDocs پیکربندی کنید. شما OAUTH را در دو مکان پیکربندی می کنید:

  1. یک طرح امنیتی برای هر تجدید نظر در یک مدل تحت تنظیمات امنیتی برای تجدید نظر ایجاد کنید.
  2. شناسه مشتری و راز مشتری را برای کلیه اصلاحات مدل تحت تنظیمات مدل مشخص کنید.

برای فعال کردن OAUTH:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. انتخاب کنید محتوا> SmartDocs در منوی مدیریت دروپال.
  3. برای مدل مورد نظر ، نسخه های API را تحت عملیات انتخاب کنید.
  4. برای تجدید نظر در مدل که می خواهید ویرایش کنید ، تنظیمات امنیتی را تحت عملیات انتخاب کنید.
  5. Add Security Security را انتخاب کنید.
  6. نام طرح امنیتی را مشخص کنید.
  7. OAUTH 2.0 را به عنوان نوع انتخاب کنید.
  8. نوع کمک هزینه را تنظیم کنید.
  9. مقادیر را در قسمتهای URL مجوز وارد کنید. URL مجوز برای به دست آوردن نشانه دسترسی استفاده می شود.
  10. فعل مجوز را به عنوان دریافت یا ارسال تنظیم کنید.
  11. URL Access Token را وارد کنید. URL Access Token URL است که برای تبادل نشانه درخواست برای یک نشانه دسترسی استفاده می شود.
  12. نام Param Access Token را وارد کنید.
  13. برای مشخص کردن نحوه عبور از نشانه: هدر ، پرس و جو یا بدنه استفاده کنید.
  14. دامنه های OAUTH را تنظیم کنید.
  15. ارسال را انتخاب کنید.
  16. انتخاب کنید محتوا> SmartDocs در منوی مدیریت دروپال.
  17. برای مدل ، تنظیمات را در پایین آمدن عملیات انتخاب کنید.
  18. مقادیر موجود در شناسه مشتری و راز مشتری را وارد کنید.
  19. تنظیمات تأیید اعتبار را انتخاب کنید.
  20. برای هر روش در مدل ، این روش را ویرایش کنید تا طرح امنیتی خود را بر روی طرح امنیتی OAUTH خود تنظیم کنید.
    1. انتخاب کنید محتوا> SmartDocs در منوی مدیریت دروپال.
    2. برای مدل مورد نظر ، نسخه های API را تحت عملیات انتخاب کنید.
    3. برای تجدید نظر در مدل که می خواهید ویرایش کنید ، جزئیات Revision را تحت عملیات انتخاب کنید.
    4. روش ویرایش را برای API که می خواهید ویرایش کنید انتخاب کنید.
    5. طرح امنیتی را برای API انتخاب کنید.
    6. API را ذخیره کنید .

پیکربندی احراز هویت توکن سفارشی

می توانید یک مدل را برای استفاده از تأیید هویت توکن سفارشی پیکربندی کنید.

برای فعال کردن نشانه های سفارشی:

  1. به عنوان یک کاربر با امتیازات مدیریت یا ایجاد محتوا وارد پورتال خود شوید.
  2. انتخاب کنید محتوا> SmartDocs در منوی مدیریت دروپال.
  3. برای مدل مورد نظر ، نسخه های API را تحت عملیات انتخاب کنید.
  4. برای تجدید نظر در مدل که می خواهید ویرایش کنید ، تنظیمات امنیتی را تحت عملیات انتخاب کنید.
  5. برنامه امنیتی Add را انتخاب کنید.
  6. نام طرح امنیتی را مشخص کنید.
  7. Apikey را به عنوان نوع انتخاب کنید.
  8. نام پارام حاوی توکن را تنظیم کنید.
  9. برای مشخص کردن نحوه عبور از نشانه: هدر ، پرس و جو یا بدنه استفاده کنید.
  10. ارسال را انتخاب کنید.
  11. برای هر روش در مدل ، روش را ویرایش کنید تا طرح امنیتی خود را بر روی طرح توکن خود تنظیم کنید.
    1. انتخاب کنید محتوا> SmartDocs در منوی مدیریت دروپال.
    2. برای مدل مورد نظر ، نسخه های API را تحت عملیات انتخاب کنید.
    3. برای تجدید نظر در مدل که می خواهید ویرایش کنید ، جزئیات Revision را تحت عملیات انتخاب کنید.
    4. روش ویرایش را برای API که می خواهید ویرایش کنید انتخاب کنید.
    5. طرح امنیتی را برای API انتخاب کنید.
    6. API را ذخیره کنید .

حذف یک مدل

هنگامی که یک مدل ( محتوا> SmartDocs را حذف می کنید ، در قسمت عملیات در دروپال حذف می شوید ) ، این مدل از سازمان Edge شما حذف می شود. این بدان معناست که اگر پورتال های دیگر به مدل مراجعه کنند ، مدل دیگر در دسترس نیست. برای اطلاعات بیشتر ، در مورد مدل ها و الگوهای SmartDoc مراجعه کنید.