Menganalisis API di pusat API Anda - Dikelola Microsoft

Pusat API organisasi Anda mencakup kemampuan linting yang dikelola langsung oleh Microsoft (pratinjau) untuk menganalisis definisi API memastikan 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. Linting definisi API Anda dilakukan secara otomatis dengan spectral:oas sekumpulan aturan (panduan gaya API).
• Laporan analisis API dihasilkan dalam portal Azure, menunjukkan bagaimana definisi API Anda sesuai dengan panduan gaya.
• Gunakan profil analisis untuk menentukan kondisi aturan dan filter untuk API yang dianalisis. Sesuaikan kumpulan aturan profil menggunakan ekstensi Azure API Center untuk Visual Studio Code.

Penting

Jika mau, Anda dapat mengaktifkan linting dan analisis secara mandiri menggunakan fungsi Azure kustom, menggantikan 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.
• Ada batasan jumlah profil analisis dan 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 memilikinya, 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.

Mengelola profil analisis

Azure API Center menggunakan profil analisis untuk melakukan linting dan menganalisis API. Profil analisis menentukan set aturan dan secara opsional memfilter kondisi untuk API yang dianalisis. Profil analisis default menerapkan spectral:oas set aturan ke semua definisi OpenAPI dan AsyncAPI.

Anda dapat menyesuaikan kumpulan aturan dan menentukan kondisi filter di profil default, atau Anda dapat membuat profil baru. Misalnya, Anda mungkin ingin menggunakan satu profil untuk API yang sedang dalam pengembangan dan yang berbeda untuk API yang sedang dalam produksi.

Note

Dalam paket Standar API Center, Anda dapat membuat hingga tiga profil analisis. Hanya satu profil yang didukung dalam paket Gratis.

Untuk membuat profil analisis:

1. Di portal Microsoft Azure, navigasikan ke pusat API Anda.
2. Di menu sebelah kiri, di bawah Tata Kelola, pilih Analisis> APIKelola profil> analisis+ Buat profil analisis.
3. Di panel Buat profil analisis baru , masukkan Nama dan Deskripsi untuk profil tersebut.
4. Di Ruleset, jenis penganalisis (mesin linting) untuk ruleset muncul. Saat ini hanya Spectral yang didukung.
5. Di bawah Tentukan kondisi filter, tambahkan satu atau beberapa kondisi filter untuk definisi API tempat profil diterapkan.
6. Pilih Buat.

Profil dibuat dan kerangka aturan dibuat. Untuk melihat kumpulan aturan saat ini, pilih profil, dan di menu konteks (...), pilih Tampilkan set aturan.

Untuk mengkustomisasi set aturan, lanjutkan ke bagian berikut.

Mengkustomisasi kumpulan aturan profil

Gunakan ekstensi Visual Studio Code untuk Azure API Center untuk menyesuaikan kumpulan aturan profil. Setelah menyesuaikan set aturan dan mengujinya secara lokal, Anda dapat menyebarkannya kembali ke pusat API Anda.

1. Di Visual Studio Code, pilih ikon Azure API Center dari Bilah Aktivitas.
2. Di panel PUSAT API, perluas sumber daya pusat API yang sedang Anda kerjakan, dan perluas Profil.
3. Perluas profil yang ingin Anda ubah, dan pilih ruleset.yaml.
4. Ubah atau ganti konten sesuai kebutuhan.
5. Simpan perubahan Anda ke ruleset.yaml.

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 yang Aktif dan tekan Enter.

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

   Langkah ini menjadikan aturan kustom sebagai panduan gaya API yang aktif untuk linting lokal.

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. Perluas Profil.
4. Klik kanan profil tempat Anda menyesuaikan set 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 di profil.

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