Menganalisis API di pusat API Anda - Dikelola Microsoft

Pusat API organisasi Anda mencakup kemampuan linting bawaan yang dikelola Microsoft (pratinjau) untuk menganalisis definisi API untuk kepatuhan terhadap aturan gaya organisasi, menghasilkan laporan individual dan ringkasan. Analisis API mengidentifikasi dan membantu Anda memperbaiki kesalahan umum dan inkonsistensi dalam definisi API Anda.

Dengan analisis API:

• Azure API Center secara otomatis menganalisis definisi API Anda setiap kali Anda menambahkan atau memperbarui definisi API. Definisi API dilintir secara default dengan spectral:oas ruleset (panduan gaya API).
• Laporan analisis API dihasilkan dalam portal Azure, menunjukkan bagaimana definisi API Anda sesuai dengan panduan gaya.
• Anda dapat menggunakan ekstensi Azure API Center untuk Visual Studio Code untuk menyesuaikan dan menguji panduan gaya API Anda sendiri secara lokal lalu menyebarkannya ke pusat API Anda.

Penting

Jika mau, Anda dapat mengaktifkan linting dan analisis yang dikelola sendiri menggunakan fungsi Azure kustom, mengganti kemampuan bawaan. Nonaktifkan fungsi apa pun yang digunakan untuk linting yang dikelola sendiri sebelum menggunakan analisis API terkelola.

Batasan

• Saat ini, hanya dokumen spesifikasi OpenAPI dan AsyncAPI dalam format JSON atau YAML yang dianalisis.
• Saat ini, Anda mengonfigurasi satu set aturan, dan diterapkan ke semua definisi OpenAPI di pusat API Anda.
• Ada batasan untuk jumlah maksimum definisi API yang dianalisis. Analisis dapat memakan waktu beberapa menit hingga 24 jam untuk diselesaikan.

Prasyarat

• Pusat API di langganan Azure Anda. Jika Anda belum membuatnya, lihat Mulai Cepat: Membuat pusat API Anda.
• Untuk menyesuaikan set aturan, Visual Studio Code , dan ekstensi Visual Studio Code berikut:
  • Ekstensi Azure API Center untuk Visual Studio Code
  • Ekstensi spectral untuk Visual Studio Code

Melihat laporan analisis API

Lihat ringkasan analisis dan laporan analisis untuk definisi API Anda di portal Azure. Setelah definisi API dianalisis, laporan mencantumkan kesalahan, peringatan, dan informasi berdasarkan panduan gaya API yang dikonfigurasi.

Dalam laporan analisis API, tinjau juga seperangkat aturan yang digunakan untuk analisis dan riwayat linting pass.

Untuk melihat ringkasan analisis di pusat API Anda:

1. Di portal, navigasikan ke pusat API Anda.

2. Di menu sebelah kiri, di bawah Tata Kelola, pilih Analisis API. Ringkasan muncul.

   

3. Secara opsional pilih ikon Laporan Analisis API untuk definisi API. Laporan analisis API definisi muncul, seperti yang ditunjukkan pada cuplikan layar berikut.

   

   Tip

   Anda juga dapat melihat laporan analisis API dengan memilih Analisis dari bilah menu definisi API.

Mengkustomisasi set aturan

Anda dapat menggunakan ekstensi Azure API Center untuk Visual Studio Code untuk menyesuaikan set aturan default untuk pusat API Anda atau menggantinya sebagai panduan gaya API organisasi Anda. Misalnya, Anda dapat memperluas set aturan atau menambahkan fungsi kustom.

Untuk menyesuaikan atau mengganti set aturan:

1. Di Visual Studio Code, pilih ikon Azure API Center dari Bilah Aktivitas.
2. .api-center-rules Buka folder di akar folder kerja Anda.
3. Di folder untuk sumber daya pusat API Anda, buka ruleset.yml file .
4. Ubah atau ganti konten sesuai kebutuhan.
5. Simpan perubahan Anda ke ruleset.yml.

Menguji ruleset secara lokal

Sebelum menyebarkan set aturan kustom ke pusat API Anda, validasi secara lokal. Ekstensi Azure API Center untuk Visual Studio Code menyediakan dukungan terintegrasi untuk linting spesifikasi API dengan Spectral.

1. Di Visual Studio Code, gunakan pintasan keyboard Ctrl+Shift+P untuk membuka Palet Perintah.

2. Ketik Azure API Center: Atur Panduan Gaya API aktif dan tekan Enter.

3. Pilih Pilih File Lokal dan tentukan ruleset.yml file yang Anda sesuaikan. Tekan Enter.

   Langkah ini membuat aturan kustom menjadi panduan gaya API aktif untuk linting.

Sekarang, saat Anda membuka file definisi API berbasis OpenAPI, operasi linting lokal secara otomatis dipicu di Visual Studio Code. Hasil ditampilkan sebaris di editor dan di jendela Masalah (Lihat > Masalah atau Ctrl+Shift+M).

Tip

Pengembang API di organisasi Anda juga dapat menggunakan kemampuan linting lokal ini untuk membantu meningkatkan definisi API mereka sebelum mendaftarkan API di pusat API Anda.

Tinjau hasil linting. Lakukan penyesuaian yang diperlukan pada set aturan dan terus uji secara lokal sampai sesuai keinginan Anda.

Menyebarkan ruleset ke pusat API Anda

Untuk menyebarkan set aturan kustom ke pusat API Anda:

1. Di Visual Studio Code, pilih ikon Azure API Center dari Bilah Aktivitas.
2. Di panel API Center, perluas sumber daya pusat API tempat Anda menyesuaikan set aturan.
3. Klik kanan Aturan dan pilih Sebarkan Aturan ke API Center.

Pesan memberi tahu Anda setelah aturan berhasil disebarkan ke pusat API Anda. Mesin linting menggunakan set aturan yang diperbarui untuk menganalisis definisi API.

Untuk melihat hasil linting dengan ruleset yang diperbarui, lihat laporan analisis API di portal.

Konten terkait

• Untuk mempelajari selengkapnya tentang kumpulan aturan bawaan default, lihat repositori Spectral GitHub.
• Mengaktifkan analisis API di pusat API Anda - dikelola sendiri