Swashbuckle.AspNetCore
v7.0.0
| PEMBERITAHUAN PENTING Jika Anda meningkatkan antara versi utama! |
|---|
| * Jika Anda meningkatkan dari 4.x ke 5.x, ada beberapa perubahan yang harus diperhatikan. Lihat catatan rilis untuk detailnya * Jika Anda melakukan lompatan dari 3.x ke 4.x terlebih dahulu, ada naga di sana juga. Lihat catatan rilis itu di sini |
Perangkat Swagger untuk API yang dibangun dengan ASP.NET Core. Hasilkan dokumentasi API yang indah, termasuk UI untuk mengeksplorasi dan menguji operasi, langsung dari rute, pengontrol, dan model Anda.
Selain generator kesombongan 2.0 dan OpenAPI 3.0, Swashbuckle juga menyediakan versi tertanam dari Swagger-UI yang mengagumkan yang ditenagai oleh JSON Swagger yang dihasilkan. Ini berarti Anda dapat melengkapi API Anda dengan dokumentasi hidup yang selalu selaras dengan kode terbaru. Yang terbaik dari semuanya, ini membutuhkan pengkodean dan pemeliharaan minimal, memungkinkan Anda untuk fokus membangun API yang luar biasa.
Dan bukan itu semua ...
Setelah Anda memiliki API yang dapat menggambarkan dirinya sendiri dalam kesombongan, Anda telah membuka peti harta karun alat berbasis Swagger termasuk generator klien yang dapat ditargetkan ke berbagai platform populer. Lihat Swagger-Codegen untuk lebih jelasnya.
| Versi swashbuckle | Inti ASP.NET | Spesifikasi Swagger / OpenAPI. | Swagger-ui | Redoc ui |
|---|---|---|---|---|
| Ci | > = 2.0.0 | 2.0, 3.0 | 5.xx | 2.xx |
| 6.9.0 | > = 2.0.0 | 2.0, 3.0 | 5.17.14 | 2.1.5 |
| 5.6.3 | > = 2.0.0 | 2.0, 3.0 | 3.32.5 | 2.0.0-rc.40 |
| 4.0.0 | > = 2.0.0, <3.0.0 | 2.0 | 3.19.5 | 1.22.2 |
| 3.0.0 | > = 1.0.4, <3.0.0 | 2.0 | 3.17.1 | 1.20.0 |
| 2.5.0 | > = 1.0.4, <3.0.0 | 2.0 | 3.16.0 | 1.20.0 |
Instal Paket Nuget Standar ke dalam Aplikasi Inti ASP.NET Anda.
Package Manager : Install-Package Swashbuckle.AspNetCore CLI : dotnet add package Swashbuckle.AspNetCore
Dalam metode ConfigureServices Startup.cs , daftarkan generator Swagger, mendefinisikan satu atau lebih dokumen Swagger.
menggunakan microsoft.openapi.models;
services.addmvc (); services.addswaggengen (c => {c.swaggerDoc ("v1", openapiinfo baru {title = "my api", version = "v1"});});Pastikan tindakan dan parameter API Anda dihiasi dengan binding "http" dan "dari" yang eksplisit.
[Httppost] public void createProduct ([frombody] produk produk) ...
[Httpget] public iEnumerable <product> pencarian produk ([fromQuery] string kata kunci) ...
Catatan: Jika Anda menghilangkan binding parameter eksplisit, generator akan menggambarkannya sebagai "kueri" params secara default.
Dalam metode Configure , Anda harus mengekspos kesombongan yang dihasilkan sebagai titik akhir JSON dengan salah satu metode berikut:
app.mapendPoints (endpoints => {// ... endpoints.mapswagger ();});app.useswagger ();
Pada titik ini, Anda dapat memutar aplikasi Anda dan melihat Swagger JSON yang dihasilkan di "/swagger/v1/swagger.json."
Masukkan middleware
Tambahkan titik akhir jika Anda menggunakan perutean berbasis titik akhir.
Secara opsional, masukkan middleware SWAGGER-UI jika Anda ingin mengekspos dokumentasi interaktif, menentukan titik akhir Swagger JSON untuk menyalakannya.
app.useswaggerui (c => {c.swaggerendpoint ("v1/swagger.json", "API v1 saya");});Sekarang Anda dapat memulai kembali aplikasi Anda dan memeriksa dokumen interaktif yang dihasilkan secara otomatis di "/Swagger".
Dalam versi sebelum 5.0.0 , Swashbuckle akan menghasilkan skema (deskripsi tipe data yang diekspos oleh API) berdasarkan perilaku Serializer NewTonsoft . Ini masuk akal karena itu adalah serializer yang dikirim dengan ASP.NET Core pada saat itu. Namun, karena versi 3.0.0 , ASP.NET Core memperkenalkan Serializer System.text.json (STJ) baru, dan jika Anda ingin terus menggunakan NewTonsoft , Anda perlu menginstal paket terpisah dan secara eksplisit dan secara eksplisit ikut serta. Dari Swashbuckle 5.0.0 dan di luar pola serupa digunakan. Artinya, out-of-the-box Swashbuckle akan menganggap Anda menggunakan serializer STJ dan menghasilkan skema berdasarkan perilakunya. Jika Anda menggunakan NewTonsoft , maka Anda harus menginstal paket swashbuckle terpisah dan secara eksplisit opt-in. Ini adalah langkah yang diperlukan, terlepas dari versi inti ASP.NET mana yang Anda gunakan .
Singkatnya ...
Jika Anda menggunakan System.text.json (STJ) , maka pengaturan yang dijelaskan di atas akan cukup, dan opsi/atribut STJ akan secara otomatis dihormati oleh generator Swagger.
Jika Anda menggunakan NewTonsoft , maka Anda harus menginstal paket terpisah dan secara eksplisit opt-in untuk memastikan bahwa pengaturan/atribut NewTonsoft secara otomatis dihormati oleh generator Swagger:
Package Manager : Install-Package Swashbuckle.AspNetCore.Newtonsoft CLI : dotnet add package Swashbuckle.AspNetCore.Newtonsoft
services.addmvc (); services.addswaggengen (c => {c.swaggerdoc ("v1", openapiinfo baru {title = "my api", version = "v1"});}); services.addswaggergennewtonsoftsupport (); // opt -in eksplisit - perlu ditempatkan setelah addswaggengen () Swashbuckle sangat bergantung pada ApiExplorer , lapisan API Metadata yang dikirimkan dengan ASP.NET Core. Jika Anda menggunakan Helper AddMvc untuk bootstrap tumpukan MVC, maka ApiExplorer akan terdaftar secara otomatis dan SB akan bekerja tanpa masalah. Namun, jika Anda menggunakan AddMvcCore untuk tumpukan MVC yang lebih berpasangan, Anda harus secara eksplisit menambahkan layanan ApiExplorer:
services.addmvccore (). AddapiExplorer ();
Selain itu, jika Anda menggunakan perutean konvensional (sebagai lawan dari routing atribut), setiap pengontrol dan tindakan pada pengontrol yang menggunakan perutean konvensional tidak akan diwakili dalam ApiExplorer, yang berarti Swashbuckle tidak akan dapat menemukan pengontrol tersebut dan menghasilkan Swagger Swagger operasi dari mereka. Misalnya:
app.usemvc (routes => {// Swaggen tidak akan menemukan pengontrol yang dialihkan melalui teknik ini. routes.maproute ("default", "{controller = home}/{action = index}/{id?}") ;});Anda harus menggunakan routing atribut untuk setiap pengontrol yang Anda inginkan diwakili dalam dokumen kesombongan Anda:
[Route ("example")] kelas publik examplecontroller: controller {[httpget ("")] public iacticuleResult doStuff () { / ** /}}Lihat dokumentasi perutean untuk informasi lebih lanjut.
Swashbuckle terdiri dari beberapa komponen yang dapat digunakan bersama atau secara individual tergantung pada kebutuhan Anda. Pada intinya, ada generator kesombongan, middleware untuk mengeksposnya sebagai titik akhir JSON, dan versi kemasan dari Swagger-UI. 3 paket ini dapat diinstal dengan Swashbuckle.AspNetCore "metapackage" dan akan bekerja bersama dengan mulus (lihat memulai) untuk menyediakan dokumen API yang indah yang secara otomatis dihasilkan dari kode Anda.
Selain itu, ada paket add-on (alat CLI, UI alternatif dll.) Yang dapat Anda instal dan konfigurasi secara opsional sesuai kebutuhan.
| Kemasan | Keterangan |
|---|---|
| Swashbuckle.aspnetcore.swagger | Mengekspos Swagger JSON Endpoints. Ia mengharapkan implementasi ISwaggerProvider terdaftar di dalam wadah DI, yang ditanyai untuk mengambil OpenAPIDocument(s) yang kemudian diekspos sebagai serial JSON |
| Swashbuckle.aspnetcore.swaggengen | Menyuntikkan implementasi ISwaggerProvider yang dapat digunakan oleh komponen di atas. Implementasi khusus ini menghasilkan OpenApiDocument(s) dari rute, pengontrol, dan model Anda |
| Swashbuckle.aspnetcore.swaggerui | Memperlihatkan versi tertanam dari Swagger-UI. Anda menentukan titik akhir API di mana ia dapat memperoleh Swagger JSON, dan menggunakannya untuk memberi daya dokumen interaktif untuk API Anda |
| Kemasan | Keterangan |
|---|---|
| Swashbuckle.aspnetcore.annotations | Termasuk satu set atribut khusus yang dapat diterapkan pada pengontrol, tindakan dan model untuk memperkaya kesombongan yang dihasilkan |
| Swashbuckle.aspnetcore.cli | Menyediakan antarmuka baris perintah untuk mengambil kesombongan langsung dari perakitan startup, dan menulis untuk mengajukan |
| Swashbuckle.aspnetcore.redoc | Mengekspos versi tertanam dari REDOC UI (alternatif untuk Swagger-UI) |
Paket-paket ini disediakan oleh komunitas open-source.
| Kemasan | Keterangan |
|---|---|
| Swashbuckle.aspnetcore.filters | Beberapa filter swashbuckle yang berguna yang menambahkan dokumentasi tambahan, misalnya contoh permintaan dan respons, informasi otorisasi, dll. Lihat readme untuk detail lebih lanjut |
| Unchase.swashbuckle.aspnetcore.Extensions | Beberapa ekstensi yang berguna (filter), yang menambahkan dokumentasi tambahan, misalnya menyembunyikan pathitem untuk peran yang tidak diterima, memperbaiki enum untuk pembuatan kode klien, dll. Lihat readme untuk detail lebih lanjut |
| Microelements.swashbuckle.fluentvalidation | Gunakan aturan fluentvalidasi alih -alih atribut ComponentModel untuk menambah skema Swagger yang dihasilkan |
| Mmlib.swaggerforocelot | Dokumentasi agregat atas layanan mikro secara langsung di Ocelot API Gateway |
Langkah -langkah yang dijelaskan di atas akan membuat Anda bangun dan berjalan dengan pengaturan minimal. Namun, Swashbuckle menawarkan banyak fleksibilitas untuk disesuaikan sesuai keinginan Anda. Lihat tabel di bawah ini untuk daftar lengkap opsi:
Swashbuckle.aspnetcore.swagger
Ubah jalan untuk titik akhir Swagger JSON
Memodifikasi kesombongan dengan konteks permintaan
Serialize Swagger Json dalam format 2.0
Bekerja dengan direktori virtual dan proxy terbalik
Menyesuaikan bagaimana dokumen openapi diserialisasi
Swashbuckle.aspnetcore.swaggengen
Tetapkan Operasi Eksplisit
Daftar Respons Operasi
Bendera Parameter yang Diperlukan dan Properti Skema
Menangani formulir dan mengunggah file
Menangani unduhan file
Sertakan deskripsi dari komentar XML
Menyediakan metadata API global
Menghasilkan banyak dokumen kesombongan
Hilangkan operasi yang sudah usang dan/atau properti skema
Menghilangkan operasi sewenang -wenang
Kustomisasi tag operasi (misalnya untuk pengelompokan UI)
Ubah Operasi Urutan Sort (misalnya untuk penyortiran UI)
Kustomisasi ID Skema
Mengganti skema untuk jenis tertentu
Perpanjang Generator Dengan Operasi, Skema & Filter Dokumen
Tambahkan definisi dan persyaratan keamanan
Tambahkan definisi dan persyaratan keamanan untuk auth pembawa
Warisan dan polimorfisme
Swashbuckle.aspnetcore.swaggerui
Ubah jalur relatif ke UI
Ubah judul dokumen
Ubah jalur CSS atau JS
Buat daftar beberapa dokumen kesombongan
Terapkan parameter Swagger-UI
Suntikkan JavaScript Kustom
Menyuntikkan CSS khusus
Kustomisasi index.html
Aktifkan aliran OAuth2.0
Gunakan Permintaan Sisi Klien dan Pencegat Respons
Swashbuckle.aspnetcore.annotations
Menginstal dan mengaktifkan anotasi
Metadata Operasi Enrich
Enrich Response Metadata
Metadata parameter yang memperkaya
Metadata Permintaan Memperkaya
Enrich Schema Metadata
Menerapkan filter skema ke jenis tertentu
Tambahkan tag metadata
Swashbuckle.aspnetcore.cli
Mengambil kesombongan langsung dari perakitan startup
Gunakan alat CLI dengan konfigurasi host khusus
Swashbuckle.aspnetcore.redoc
Ubah jalur relatif ke UI
Ubah judul dokumen
Terapkan parameter redoc
Menyuntikkan CSS khusus
Kustomisasi index.html
Secara default, Swagger JSON akan diekspos di rute berikut - "/swagger/{DocumentName}/swagger.json". Jika perlu, Anda dapat mengubahnya saat mengaktifkan middleware yang bergantian. Rute khusus harus menyertakan parameter {documentName} .
app.useswagger (c => {c.RouteTemplate = "API-DOCS/{DocumentName} /swagger.json";})Catatan: Jika Anda menggunakan middleware Swaggerui, Anda juga harus memperbarui konfigurasinya untuk mencerminkan titik akhir baru:
app.useswaggerui (c => {c.swaggerendpoint ("/api-docs/v1/swagger.json", "API v1 saya");})Catatan: Jika Anda juga perlu memperbarui jalur relatif yang tersedia UI itu, Anda harus mengikuti instruksi yang ditemukan di jalur relatif perubahan ke UI.
Jika Anda perlu mengatur beberapa metadata Swagger berdasarkan permintaan saat ini, Anda dapat mengonfigurasi filter yang dieksekusi sebelum membuat serial dokumen.
app.useswagger (c => {c.preserializeFilters.add ((Swagger, httpreq) => {swagger.servers = Daftar baru <Epenapiserver> {Openapiserver baru {url = $ "{httpreq.scheme}: // {httpreq. Host.Value} "}};});}); OpenApiDocument dan HttpRequest saat ini keduanya diteruskan ke filter. Ini memberikan banyak fleksibilitas. Misalnya, Anda dapat menambahkan server API eksplisit berdasarkan header "host" (seperti yang ditunjukkan), atau Anda dapat memeriksa informasi sesi atau header otorisasi dan menghapus operasi dari dokumen berdasarkan izin pengguna.
Secara default, Swashbuckle akan menghasilkan dan mengekspos Swagger JSON dalam versi 3.0 dari spesifikasi, secara resmi disebut spesifikasi OpenAPI. Namun, untuk mendukung kompatibilitas mundur, Anda dapat memilih untuk terus mengeksposnya dalam format 2.0 dengan opsi berikut:
app.useswagger (c => {c.serializeAsv2 = true;}); Direktori virtual dan proxy terbalik dapat menyebabkan masalah untuk aplikasi yang menghasilkan tautan dan pengalihan, terutama jika aplikasi mengembalikan URL absolut berdasarkan header Host dan informasi lain dari permintaan saat ini. Untuk menghindari masalah ini, Swashbuckle menggunakan URL relatif jika memungkinkan, dan mendorong penggunaannya saat mengkonfigurasi middleware Swaggerui dan Redoc.
Misalnya, untuk memasang middleware Swaggerui, Anda menyediakan URL untuk satu atau lebih dokumen OpenAPI/Swagger. Ini adalah URL yang akan diselesaikan oleh Swagger-UI, aplikasi sisi klien, akan menelepon untuk mengambil metadata API Anda. Untuk memastikan ini berfungsi di balik direktori virtual dan proxy terbalik, Anda harus mengekspresikan relatif ini terhadap RoutePrefix dari Swagger-UI itu sendiri:
app.useswaggerui (c => {c.RoutePrefix = "Swagger"; c.swaggerendpoint ("v1/swagger.json", "API v1 saya");}); Catatan: Dalam versi dokumen sebelumnya, Anda mungkin telah melihat ini dinyatakan sebagai tautan root-relative (misalnya /swagger/v1/swagger.json ). Ini tidak akan berfungsi jika aplikasi Anda di -host di direktori virtual IIS atau di belakang proxy yang memotong jalur permintaan sebelum meneruskan. Jika Anda beralih ke sintaks -halaman-relatif yang ditunjukkan di atas, itu harus berfungsi dalam semua kasus.
Secara default, Swashbuckle akan membuat serial dokumen OpenAPI menggunakan metode serialize pada objek dokumen OpenAPI. Jika serialisasi yang disesuaikan diinginkan, dimungkinkan untuk membuat serializer dokumen khusus yang mengimplementasikan antarmuka ISwaggerDocumentSerializer . Ini dapat diatur pada SwaggerOptions dalam koleksi layanan menggunakan ConfigureSwagger() :
Catatan
Jika Anda berencana menggunakan alat baris perintah untuk menghasilkan file spesifikasi OpenAPI, ini harus dilakukan pada pengumpulan layanan menggunakan ConfigureSwagger() .
services.configureswagger (option => {option.setCustomDocumenteralizer <Cust customDocumentSerializer> ();})Ketika alat baris perintah tidak digunakan, itu juga dapat dilakukan pada host aplikasi:
app.useswagger (options => {options.setCustomDocumentserializer <Cust customDocumentSerializer> ();}) Dalam kesombongan, operasi dapat ditugaskan operationId . ID ini harus unik di antara semua operasi yang dijelaskan dalam API. Alat dan perpustakaan (misalnya generator klien) dapat menggunakan OperationID untuk mengidentifikasi operasi secara unik, oleh karena itu, disarankan untuk mengikuti konvensi penamaan pemrograman umum.
Menghasilkan ID yang sesuai dengan persyaratan ini, sementara juga memberikan nama yang akan bermakna di perpustakaan klien adalah tugas non-sepele dan karenanya, Swashbuckle menghilangkan operationId secara default. Namun, jika perlu, Anda dapat menetapkan operationIds dengan mendekorasi rute individu atau dengan memberikan strategi khusus.
Opsi 1) Hiasi rute dengan properti Name
[Httpget ("{id}", name = "getProductById")] public iactionResult get (int id) // operasi = "getProductById"Opsi 2) Memberikan strategi khusus
// startup.csservices.addswaggergen (c => {... // gunakan nama metode sebagai operasi c.customoperationIds (apidesc => {return apidesc.trygetMethodinfo (out methodInfo MethodInfo)? MethodInfo.name: null;});} ) // ProductsController.cs [httpget ("{id}")] public iacticuleResult getProductById (int id) // OperationID = "getProductById" Catatan: Dengan salah satu pendekatan, penulis API bertanggung jawab untuk memastikan keunikan operationIds di semua operasi
Secara default, Swashbuckle akan menghasilkan respons "200" untuk setiap operasi. Jika tindakan mengembalikan DTO respons, maka ini akan digunakan untuk menghasilkan skema untuk badan respons. Misalnya ...
[Httppost ("{id}")] produk publik getById (int id)Akan menghasilkan metadata respons berikut:
responses: {
200: {
description: "OK",
content: {
"application/json": {
schema: {
$ref: "#/components/schemas/Product"
}
}
}
}
} Jika Anda perlu menentukan kode status yang berbeda dan/atau respons tambahan, atau tindakan Anda mengembalikan IActionResult alih -alih respons DTO, Anda dapat secara eksplisit menggambarkan tanggapan dengan ProducesResponseTypeAttribute yang dikirimkan dengan ASP.NET Core. Misalnya ...
[Httppost ("{id}")] [menghasilkan responsetype (typeof (produk), 200)] [menghasilkan responsetype (typeof (idiksi <string, string>), 400)] [menghasilkan responsetype (500)] public iactionResult getById (int id)Akan menghasilkan metadata respons berikut:
responses: {
200: {
description: "OK",
content: {
"application/json": {
schema: {
$ref: "#/components/schemas/Product"
}
}
}
},
400: {
description: "Bad Request",
content: {
"application/json": {
schema: {
type: "object",
additionalProperties: {
type: "string"
}
}
}
}
},
500: {
description: "Internal Server Error",
content: {}
}
} Dalam dokumen Swagger, Anda dapat menandai parameter dan properti skema yang diperlukan untuk permintaan. Jika parameter (tingkat atas atau berbasis properti) dihiasi dengan BindRequiredAttribute atau RequiredAttribute , maka Swashbuckle akan secara otomatis menandai parameter "yang diperlukan" dalam kesombongan yang dihasilkan:
// ProductsController.cspublic IActionResult Search([FromQuery, BindRequired]string keywords, [FromQuery]PagingParams pagingParams){if (!ModelState.IsValid)return BadRequest(ModelState);...}// SearchParams.cspublic class PagingParams{[Required ] Public Int Pageno {get; mengatur; } public int pageSize {get; mengatur; }} Selain parameter, Swashbuckle juga akan menghormati yang RequiredAttribute saat digunakan dalam model yang terikat pada badan permintaan. Dalam hal ini, properti yang didekorasi akan ditandai sebagai properti "wajib" dalam deskripsi tubuh:
// ProductsController.cspublic iActicHesult create ([frombody] Produk) {if (! ModelState.isvalid) return badrequest (modelState); ...} // Product.cspublic Class Product {[wajib] Nama string publik {get; mengatur; } deskripsi string publik {get; mengatur; }}Pengontrol ini akan menerima dua nilai bidang formulir dan satu unggahan file bernama dari formulir yang sama:
[Httppost] public void unggah ([fromForm] string description, [fromForm] datetime clientDate, file iformFile)
Catatan Penting: Sesuai dokumen Inti ASP.NET, Anda tidak seharusnya menghiasi parameter
IFormFiledengan atribut[FromForm]karena sumber pengikat secara otomatis disimpulkan dari jenis tersebut. Faktanya, nilai yang disimpulkan adalahBindingSource.FormFiledan jika Anda menerapkan atribut, itu akan diatur keBindingSource.Formsebagai gantinya, yang mengacaukanApiExplorer, komponen metadata yang dikirimkan dengan ASP.NET Core dan sangat diandalkan oleh Swashbuckle. Salah satu masalah tertentu di sini adalah bahwa Swaggerui tidak akan memperlakukan parameter sebagai file dan karenanya tidak akan menampilkan tombol unggahan file, jika Anda secara keliru menyertakan atribut ini.
ApiExplorer (komponen metadata inti ASP.NET yang dibangun swashbuckle) tidak memunculkan jenis FileResult secara default dan Anda perlu mengatakannya secara eksplisit dengan atribut ProducesResponseType (atau Produces pada .net 5 atau lebih):
[Httpget ("{filename}")] [menghasilkan responsetype (typeof (filestreamResult), statuscodes.status200ok, "gambar/jpeg")] public filestreamResult getFile (string filename)Untuk meningkatkan dokumen yang dihasilkan dengan deskripsi yang ramah manusia, Anda dapat memberi anotasi pada tindakan dan model pengontrol dengan komentar XML dan mengkonfigurasi swashbuckle untuk memasukkan komentar tersebut ke dalam JSON Swagger yang dikeluarkan:
Buka dialog Properties untuk proyek Anda, klik tab "Build" dan pastikan bahwa "File Dokumentasi XML" diperiksa, atau tambahkan elemen <GenerateDocumentationFile>true</GenerateDocumentationFile> ke bagian <PropertyGroup> dari file proyek .csproj Anda. Ini akan menghasilkan file yang berisi semua komentar XML pada waktu build.
Pada titik ini, setiap kelas atau metode yang tidak dijelaskan dengan komentar XML akan memicu peringatan build. Untuk menekan ini, masukkan kode peringatan "1591" ke dalam bidang "Suppress Warnings" di dialog Properties atau tambahkan <NoWarn>1591</NoWarn> ke bagian <PropertyGroup> dari file proyek .csproj Anda.
Konfigurasikan SwashBuckle untuk memasukkan komentar XML pada file ke dalam Swagger JSON yang dihasilkan:
services.addswaggengen (c => {c.swaggerdoc ("v1", openapiinfo baru {title = "My API - V1", Version = "V1"}); c.includexmlComments (assembly.getExecutingAssembly ()); // atau atau c.includexmlComments (typeof (myController) .Assembly));}Annotate Tindakan Anda dengan Ringkasan, Keterangan, Param dan Tag Respons:
/// <summary> /// mengambil produk tertentu dengan ID unik /// </summary> /// <pearks> Awesomeness! </petaran> /// <param name = "id" example = "123" > ID Produk </param> /// <kode respons = "200"> Produk Diperoleh </spesponse> /// <kode respons = "404"> Produk tidak ditemukan </pespess> /// <kode respons = "500"> oops! Tidak dapat mencari produk Anda saat ini </pespess> [httpget ("{id}")] [menghasilkan responsetype (typeof (produk), 200)] [menghasilkan responsetype (404)] [menghasilkan responsetype (500)] GetByIde (Int (404)] [ProducesResponsetype (500)] GetByID (Int (404)] pengenal)Anda juga dapat membuat anotasi dengan ringkasan dan contoh tag:
Produk kelas publik {/// <summary> /// Nama produk /// </summary> /// <contoh> sepatu basket pria </sel masukkan> nama string publik {get; mengatur; } /// <summary> /// kuantitas tersisa di stok /// </summary> /// <contoh> 10 </example> interablestock publik {get; mengatur; } /// <summary> /// Ukuran produk tersedia di /// </summary> /// <scontoh> ["kecil", "medium", "besar"] </contoh> daftar publik < String> Ukuran {get; mengatur; }}Bangun kembali proyek Anda untuk memperbarui file komentar XML dan menavigasi ke titik akhir JSON Swagger. Perhatikan bagaimana deskripsi dipetakan ke bidang kesombongan yang sesuai.
Catatan: Anda juga dapat memberikan deskripsi skema Swagger dengan menganotasi model API Anda dan propertinya dengan tag ringkasan. Jika Anda memiliki beberapa file komentar XML (misalnya pustaka terpisah untuk pengontrol dan model), Anda dapat memohon metode includexmlComments beberapa kali dan semuanya akan digabungkan ke dalam Swagger JSON yang dikeluarkan.
Selain "Pathitems", "Operations" dan "Responses", yang dihasilkan Swashbuckle untuk Anda, Swagger juga mendukung metadata global (lihat https://swagger.io/specification/#oasObject). Misalnya, Anda dapat memberikan deskripsi lengkap untuk API, Ketentuan Layanan atau bahkan informasi kontak dan lisensi Anda:
c.swaggerdoc ("v1", openapiinfo baru {title = "My API - V1", Version = "V1", Deskripsi = "Sampel API untuk Demo Swashbuckle", istilahfservice = Uri baru ("http://tempuri.org /istilah "), contact = new OpenapiContact {name =" Joe Developer ", email =" [email protected] "}, lisensi = Openapilicense baru {name =" Apache 2.0 ", url = URI baru (" https: //www.apache.org/licenses/license-2.0.html ")}});Kiat: Gunakan Intellisense untuk melihat bidang apa yang tersedia.
Dengan pengaturan yang dijelaskan di atas, generator akan mencakup semua operasi API dalam satu dokumen angkuh. Namun, Anda dapat membuat beberapa dokumen jika perlu. Misalnya, Anda mungkin menginginkan dokumen terpisah untuk setiap versi API Anda. Untuk melakukan ini, mulailah dengan mendefinisikan beberapa dokumen Swagger di Startup.cs :
services.addswaggengen (c => {c.swaggerdoc ("v1", openapiinfo baru {title = "My API - V1", Version = "V1"}); c.swaggerDoc ("v2", OpenApiInfo baru {title = " API saya - v2 ", versi =" v2 "});})Perhatikan argumen pertama ke SwaggerDoc. Itu pasti nama ramah URI yang secara unik mengidentifikasi dokumen. Selanjutnya digunakan untuk membentuk jalur untuk meminta Swagger JSON yang sesuai. Misalnya, dengan perutean default, dokumen di atas akan tersedia di "/swagger/v1/swagger.json" dan "/swagger/v2/swagger.json".
Selanjutnya, Anda harus menginformasikan swashbuckle tindakan mana yang akan dimasukkan dalam setiap dokumen. Meskipun ini dapat disesuaikan (lihat di bawah), secara default, generator akan menggunakan properti ApiDescription.GroupName , bagian dari lapisan metadata bawaan yang dikirimkan dengan inti ASP.NET, untuk membuat perbedaan ini. Anda dapat mengatur ini dengan mendekorasi tindakan individual atau dengan menerapkan konvensi aplikasi lebar.
Untuk memasukkan tindakan dalam dokumen Swagger tertentu, hiasi dengan ApiExplorerSettingsAttribute dan atur GroupName ke nama dokumen yang sesuai (Sensitive Case):
[Httppost] [apiexplorerSettings (groupName = "v2")] public void post ([frombody] produk produk)
Untuk dikelompokkan berdasarkan konvensi alih -alih mendekorasi setiap tindakan, Anda dapat menerapkan pengontrol khusus atau konvensi tindakan. Misalnya, Anda dapat memasang konvensi berikut untuk menetapkan tindakan ke dokumen berdasarkan namespace pengontrol.
// apiexplorergroupperversionConvention.cspublic class apiexplorergroupperversionConvention: icontrollermodelconvention {public void apply (controllerer Controller) {var controllernamespace = controller.controllerType.namespace; // misalnya "controllers.v1" var apiversion = controllernamespace.split ('.'). last (). Tolower (); controller.apiexplorer.groupName = apiversion;}} // startup.cspublic void configureServices (Layanan IServICeCollection) {startup.cspublic void (Layanan IServICECOCECOLEKSI) {startup.cspublic services.addmvc (c => c.conventions.Add (ApiExplorerGroPerVersionConvention baru ())); ...} Saat memilih tindakan untuk dokumen Swagger yang diberikan, generator meminta DocInclusionPredicate terhadap setiap ApiDescription yang muncul oleh kerangka kerja. Implementasi default memeriksa ApiDescription.GroupName dan mengembalikan true jika nilainya nol atau sama dengan nama dokumen yang diminta. Namun, Anda juga dapat memberikan predikat inklusi khusus. Misalnya, jika Anda menggunakan pendekatan berbasis atribut untuk mengimplementasikan versi API (mis.
C.DocinclusionPredicate ((docName, apidesc) => {if (! apidesc.trygetMethodinfo (out methodInfo MethodInfo)) mengembalikan false; var versi = methodInfo.declaringType .getCustOMAttributes (true) .oftype <apiversioneTribute>. > attr.versions); Jika Anda menggunakan middleware SwaggerUI , Anda harus menentukan titik akhir kesombongan tambahan yang ingin Anda ungkapkan. Lihat daftar beberapa dokumen Swagger untuk lebih lanjut.
Spesifikasi Swagger termasuk bendera deprecated untuk menunjukkan bahwa suatu operasi sudah usang dan harus ditahan agar tidak digunakan. Generator Swagger akan secara otomatis mengatur bendera ini jika tindakan yang sesuai dihiasi dengan ObsoleteAttribute . Namun, alih -alih mengatur bendera, Anda dapat mengonfigurasi generator untuk mengabaikan tindakan usang sama sekali:
services.addswaggengen (c => {... c.ignoreObsoleteactions ();}; Pendekatan serupa juga dapat digunakan untuk menghilangkan sifat usang dari skema dalam output angkuh. Artinya, Anda dapat menghiasi properti model dengan ObsoleteAttribute dan mengkonfigurasi Swashbuckle untuk menghilangkan properti tersebut saat menghasilkan skema JSON:
services.addswaggengen (c => {... c.ignoreObsoleteProperties ();};Anda dapat menghilangkan operasi dari output Swagger dengan mendekorasi tindakan individu atau dengan menerapkan konvensi aplikasi lebar.
Untuk menghilangkan tindakan tertentu, hiasi dengan ApiExplorerSettingsAttribute dan atur bendera IgnoreApi :
[Httpget ("{id}")] [ApiExPlorersettings (IgnoreApI = true)] Produk Publik GetByID (Int ID)Untuk menghilangkan tindakan berdasarkan konvensi alih -alih mendekorasi mereka secara individual, Anda dapat menerapkan Konvensi Tindakan Kustom. Misalnya, Anda dapat memasang konvensi berikut untuk hanya mendokumentasikan operasi:
// apiexplorergetsonlyconvention.cspublic class apiexplorergetsonlyconvention: iActionModelConvention {public void berlaku (ActionModel Action) {action.apiexplorer.isvisible = action.attributes.oftype <httpgetattribute> (). layanan) {services.addmvc (c => c.conventions.add (ApiExplorerGetSonlyConvention ()) baru Spec Swagger memungkinkan satu atau lebih "tag" untuk ditugaskan untuk operasi. Generator Swagger akan menetapkan nama pengontrol sebagai tag default. Ini penting untuk dicatat jika Anda menggunakan middleware SwaggerUI karena menggunakan nilai ini untuk mengelompokkan operasi.
Anda dapat mengganti tag default dengan menyediakan fungsi yang berlaku tag berdasarkan konvensi. Misalnya, konfigurasi berikut akan menandai, dan oleh karena itu grup operasi di UI, dengan metode HTTP:
services.addswaggengen (c => {... c.tagactionsby (API => API.httpMethod);};Secara default, tindakan diperintahkan dengan tag yang ditetapkan (lihat di atas) sebelum dikelompokkan ke dalam struktur jalur-sentris, bersarang dari spec Swagger. Tapi, Anda dapat mengubah pemesanan tindakan default dengan strategi penyortiran khusus:
services.addswaggengen (c => {... c.orderactionsby ((apidesc) => $ "{apidesc.actionDescriptor.RoutEvalues [" controller "]} _ {apidesc.httpmethod}");};Catatan: Ini menentukan urutan semacam sebelum tindakan dikelompokkan dan diubah menjadi format kesombongan. Jadi, itu mempengaruhi pemesanan kelompok (yaitu "pathitems" kesombongan), dan pemesanan operasi dalam suatu kelompok, dalam output kesombongan.
Jika generator menemukan parameter kompleks atau jenis respons, itu akan menghasilkan skema JSON yang sesuai, tambahkan ke Kamus components/schemas Global, dan merujuknya dari deskripsi operasi dengan ID unik. Misalnya, jika Anda memiliki tindakan yang mengembalikan jenis Product , maka skema yang dihasilkan akan direferensikan sebagai berikut:
responses: {
200: {
description: "OK",
content: {
"application/json": {
schema: {
$ref: "#/components/schemas/Product"
}
}
}
}
} Namun, jika bertemu banyak jenis dengan nama yang sama tetapi ruang nama yang berbeda (misalnya RequestModels.Product & ResponseModels.Product ), maka Swashbuckle akan meningkatkan pengecualian karena "skema yang bertentangan". Dalam hal ini, Anda harus memberikan strategi ID khusus yang lebih memenuhi syarat nama:
services.addswaggengen (c => {... c.customschemaids ((type) => type.fullname);};Lihat #2703 untuk dukungan untuk jenis bersarang.
Di luar kotak, Swashbuckle melakukan pekerjaan yang layak untuk menghasilkan skema JSON yang secara akurat menggambarkan permintaan dan muatan tanggapan Anda. Namun, jika Anda menyesuaikan perilaku serialisasi untuk jenis tertentu di API Anda, Anda mungkin perlu membantunya.
Misalnya, Anda mungkin memiliki kelas dengan banyak properti yang ingin Anda wakili di JSON sebagai string yang dipisahkan koma. Untuk melakukan ini, Anda mungkin akan mengimplementasikan JsonConverter khusus. Dalam hal ini, Swashbuckle tidak tahu bagaimana konverter diimplementasikan sehingga Anda perlu menyediakan skema yang secara akurat menggambarkan jenisnya:
// phonenumber.cspublic class phonenumber {public string countrycode {get; mengatur; } public String AreaCode {get; mengatur; } public String SubscriberID {get; mengatur; }} // startup.csservices.addswaggergen (c => {... c.maptype <phonenumber> (() => Openapischema baru {type = "string"});};Swashbuckle memperlihatkan pipa filter yang menghubungkan ke dalam proses pembuatan. Setelah dihasilkan, objek metadata individu diteruskan ke dalam pipa di mana mereka dapat dimodifikasi lebih lanjut. Anda dapat memasang filter khusus untuk memperkaya "operasi" yang dihasilkan, "skema" dan "dokumen".
Swashbuckle mengambil ApiDescription , bagian dari ASP.NET Core, untuk setiap tindakan dan menggunakannya untuk menghasilkan OpenApiOperation yang sesuai. Setelah dihasilkan, ia melewati OpenApiOperation dan ApiDescription melalui daftar filter operasi yang dikonfigurasi.
Dalam implementasi filter yang khas, Anda akan memeriksa ApiDescription untuk informasi yang relevan (misalnya info rute, atribut tindakan dll.) Dan kemudian memperbarui OpenApiOperation sesuai. Misalnya, filter berikut mencantumkan respons "401" tambahan untuk semua tindakan yang didekorasi dengan AuthorizeAttribute :
// authresponsePerationFilter.cspublic class authresponsePerationFilter: iOperationFilter {public void berlaku (operasi openapioperation, OperationFiltercontext Context.declarype.declaryple) {var authattributes = context.methodinfo.declarype.getcustom (context AuthorizeAttribute > (); if (authattributes.any ()) operasi.Responses.add ("401", OpenApiresponse baru {description = "tidak sah"});}} // startup.csservices.addswaggen (c => {... C.OperationFilter <OuthResponseSoperationFilter> ();};CATATAN: Palangan pipa filter di-sadar. Artinya, Anda dapat membuat filter dengan parameter konstruktor dan jika jenis parameter terdaftar dengan kerangka DI, mereka akan secara otomatis disuntikkan ketika filter dipakai
Swashbuckle menghasilkan jsonschema rasa angkuh untuk setiap parameter, respons, dan jenis properti yang diekspos oleh tindakan pengontrol Anda. Setelah dihasilkan, ia melewati skema dan mengetik melalui daftar filter skema yang dikonfigurasi.
Contoh di bawah ini menambahkan ekstensi vendor autorest (lihat https://github.com/azure/autorest/blob/master/docs/extensions/readme.md#x-ms-enum) untuk menginformasikan alat autorest bagaimana enum harus dimodelkan Saat menghasilkan klien API.
// autorestschemafilter.cspublic class autorestschemafilter: ischemafilter {public void apply (skema openapischema, schemaFilterContext konteks) {var type = context.type; if (type.isenum) {schema.extensions.add ("x-mss-enum), schema.extensions.add (" x-mss-esum OpenApIObject {["name"] = Openapistring baru (type.name), ["ModelAsstring"] = OpenApiboolean baru (true)});};}} // startup.csservices.addswaggengen (c => {... c .Schemafilter <OutorestSchemafilter> ();}; Contoh di bawah ini memungkinkan untuk pembuatan skema otomatis Dictionary<Enum, TValue> objek. Perhatikan bahwa ini hanya menghasilkan kesombongan; System.Text.Json tidak dapat mengurai Kamus enum secara default, jadi Anda akan memerlukan JsonConverter khusus, seperti di .NET Documents
// DictionarytKeyEnumtValuesChemafilter.cspublic Kelas DictionarytKeyenUMtValuesChemAfilter: IschemaFilter {
public void berlaku (Openapischema Schema, SchemaFilterContext Context)
{// Hanya jalankan untuk bidang yang merupakan kamus <enum, tvalue> if (! Context.type.isgenerictype ||! Context.type.getGenerictypeDefinition (). IsassignableFrom (typeof (kamus <,>)) {return;} var keytype = context.type.getGenericArguments () [0]; var valueType = context.type.getGenericArguments () [1]; if (! keytype.isenum) {return;} schema.type = "objek"; schema.properties) = keytype.getEnumnames (). Todictionary (name => name, name => context.schemagenerator.genateSeateSchema (valueType, context.schemarepository));
}} // startup.csservices.addswaggergen (c => {... // Ini akan digantikan oleh DictionarytKeyEnumtValuesChemafilter, tetapi diperlukan untuk menghindari kesalahan.// Anda akan membutuhkannya untuk setiap jenis kamus <,> Anda punya .c.maptype <Dictionary <myenum, list <string>> (() => OpenapisChema baru ()); c.schemafilter <ctictiyarytkeyenumtvalueschemafilter> ();}; Setelah OpenApiDocument dihasilkan, itu juga dapat dilewatkan melalui serangkaian filter dokumen yang telah dikonfigurasi sebelumnya. Ini memberikan kontrol penuh untuk memodifikasi dokumen yang Anda inginkan. Untuk memastikan Anda masih mengembalikan Swagger JSON yang valid, Anda harus membaca spesifikasi sebelum menggunakan jenis filter ini.
Contoh di bawah ini memberikan deskripsi untuk setiap tag yang ditetapkan untuk operasi dalam dokumen:
TagDescriptionSdocumentFilter {Name = "orders", description = "Kirim pesanan"}};}} Catatan: Jika Anda menggunakan middleware SwaggerUI , TagDescriptionsDocumentFilter yang ditunjukkan di atas dapat digunakan untuk menampilkan deskripsi tambahan di samping setiap kelompok operasi.
Dalam Swagger, Anda dapat menggambarkan bagaimana API Anda diamankan dengan mendefinisikan satu atau lebih skema keamanan (misalnya dasar, kunci API, OAuth2 dll.) Dan menyatakan skema mana yang berlaku secara global atau untuk operasi tertentu. Untuk detail lebih lanjut, lihatlah objek persyaratan keamanan dalam spesifikasi Swagger ..
Di Swashbuckle, Anda dapat mendefinisikan skema dengan menggunakan metode AddSecurityDefinition , memberikan nama dan contoh OpenApiSecurityScheme . Misalnya Anda dapat mendefinisikan OAuth 2.0 - Aliran implisit sebagai berikut:
// Startup.csservices.AddSwaggerGen(c =>{ ... // Define the OAuth2.0 scheme that's in use (ie Implicit Flow) c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme { Type = SecuritySchemeType.OAuth2, Flows = OpenapioAuthflows baru {implicit = OpenApioAuthflow baru {otorizationUrl = new Uri ("/auth-server/connect/otorize", urikind.relative), scopes = kamus baru <string, string> {"readAccess", "akses baca"}} , {"WriteAccess", "Access Write Operations"}}}}});}; Catatan: Selain mendefinisikan skema, Anda juga perlu menunjukkan operasi mana yang berlaku untuk skema. Anda dapat menerapkan skema secara global (yaitu ke semua operasi) melalui metode AddSecurityRequirement . Contoh di bawah ini menunjukkan bahwa skema yang disebut "OAuth2" harus diterapkan pada semua operasi, dan bahwa lingkup "readaccess" dan "writeaccess" diperlukan. Saat menerapkan skema jenis selain "OAuth2", array lingkup harus kosong.
c.AddSwaggerGen(c =>{ ... c.AddSecurityRequirement(new OpenApiSecurityRequirement { { new OpenApiSecurityScheme { Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "oauth2" } }, new[] { "readAccess", " writeaccess "}}});}) Jika Anda memiliki skema yang hanya berlaku untuk operasi tertentu, Anda dapat menerapkannya melalui filter operasi. Misalnya, filter berikut menambahkan persyaratan OAuth2 berdasarkan kehadiran AuthorizeAttribute :
// SecurityRequirementsOperationFilter.cspublic Class SecurityRequirementsOperationFilter: iOperationFilter {public void berlaku (Operasi OpenApioperation, OperationFilterContext Context) {// Nama Kebijakan Peta ke ScopesVar wajib ScopesScopes = Context.methodinfo.getcustomatribute (true). > attr.policy) .distinct (); if (wajib dibutuhkan. OpenApiresponse baru {description = "Forbidden"}); var oAuthscheme = OpenapisecurityScheme baru {referensi = OpenApireference baru {type = ReferenceType.securitysCheme, id = "oauth2"}}; Operasi. oAuthscheme] = wajibcopes.tolist ()}};}}} Catatan: Jika Anda menggunakan middleware SwaggerUI , Anda dapat mengaktifkan aliran OAuth2.0 interaktif yang ditenagai oleh metadata keamanan yang dipancarkan. Lihat Mengaktifkan aliran OAuth2.0 untuk lebih jelasnya.
services.addswaggengen (c => {c.addsecurityDefinition ("bearerAuth", OpenapisecurityScheme baru {type = SecuritySchemetype.http, Scheme = "Bearer", BearerFormat = "JWT", Deskripsi = "JWT Header Otorisasi Menggunakan Skema Pembawa."} ); Swagger / OpenAPI mendefinisikan allOf kata kunci dan oneOf kata kunci untuk menggambarkan hubungan warisan dan polimorfisme dalam definisi skema. Misalnya, jika Anda menggunakan kelas dasar untuk model yang berbagi properti umum, Anda dapat menggunakan kata kunci allOf untuk menggambarkan hierarki warisan. Atau, jika serializer Anda mendukung serialisasi/deserialisasi polimorfik, Anda dapat menggunakan kata kunci oneOf untuk mendokumentasikan semua skema "yang mungkin" untuk permintaan/respons yang bervariasi berdasarkan subtipe.
Secara default, Swashbuckle meratakan hierarki warisan. Artinya, untuk model yang diturunkan, sifat yang diwariskan digabungkan dan terdaftar di samping properti yang dinyatakan. Ini dapat menyebabkan banyak duplikasi dalam kesombongan yang dihasilkan, terutama ketika ada beberapa subtipe. Ini juga bermasalah jika Anda menggunakan generator klien (misalnya NSWAG) dan ingin mempertahankan hierarki warisan dalam model klien yang dihasilkan. Untuk mengatasi hal ini, Anda dapat menerapkan pengaturan UseAllOfForInheritance , dan ini akan memanfaatkan kata kunci allOf untuk menggabungkan properti yang diwariskan dengan referensi dalam Swagger yang dihasilkan:
Circle: {
type: "object",
allOf: [
{
$ref: "#/components/schemas/Shape"
}
],
properties: {
radius: {
type: "integer",
format: "int32",
}
},
},
Shape: {
type: "object",
properties: {
name: {
type: "string",
nullable: true,
}
},
} Jika serializer Anda mendukung serialisasi/deserialisasi polimorfik dan Anda ingin membuat daftar subtipe yang mungkin untuk tindakan yang menerima/mengembalikan jenis dasar abstrak, Anda dapat menerapkan pengaturan UseOneOfForPolymorphism . Akibatnya, skema permintaan/respons yang dihasilkan akan merujuk koleksi skema "yang mungkin", bukan hanya skema kelas dasar:
requestBody: {
content: {
application/json: {
schema: {
oneOf: [
{
$ref: "#/components/schemas/Rectangle"
},
{
$ref: "#/components/schemas/Circle"
},
],
}
}
}Karena hubungan warisan dan polimorfisme seringkali menjadi sangat kompleks, tidak hanya dalam model Anda sendiri tetapi juga di dalam perpustakaan kelas .NET, Swashbuckle selektif tentang hierarki yang dilakukannya dan tidak mengekspos dalam kesombongan yang dihasilkan. Secara default, ia akan mengambil subtipe yang didefinisikan dalam perakitan yang sama sebagai jenis dasar yang diberikan. Jika Anda ingin mengganti perilaku ini, Anda dapat memberikan fungsi pemilih khusus:
services.addswaggengen (c => {... c.useallofforinHeritance (); c.selectsubTypeSusing (basetype => {return typeof (startup) .Assembly.getTypes (). Di mana (type => type.issubclassOf (basetype)); })}); Catatan: Jika Anda menggunakan perpustakaan anotasi Swashbuckle, itu berisi pemilih khusus yang didasarkan pada keberadaan atribut SwaggerSubType pada definisi kelas dasar. Dengan cara ini, Anda dapat menggunakan atribut sederhana untuk secara eksplisit mencantumkan hubungan warisan dan/atau polimorfisme yang ingin Anda ungkapkan. Untuk mengaktifkan perilaku ini, lihat dokumen anotasi.
Sehubungan dengan kata kunci oneOf dan / atau allOf , Swagger / OpenAPI mendukung bidang discriminator pada definisi skema dasar. Kata kunci ini menunjuk ke properti yang mengidentifikasi jenis spesifik yang diwakili oleh muatan yang diberikan. Selain nama properti, deskripsi diskriminator juga dapat mencakup mapping yang memetakan nilai diskriminator ke definisi skema tertentu.
Misalnya, serializer NewTonsoft mendukung serialisasi/deserialisasi polimorfik dengan memancarkan/menerima properti "$ tipe" pada instance JSON. Nilai properti ini akan menjadi nama tipe berkualifikasi Majelis dari jenis yang diwakili oleh instance JSON yang diberikan. Jadi, untuk menggambarkan perilaku ini secara eksplisit dalam kesombongan, skema permintaan/respons yang sesuai dapat didefinisikan sebagai berikut:
components: {
schemas: {
Shape: {
required: [
"$type"
],
type: "object",
properties: {
$type: {
type": "string"
},
discriminator: {
propertyName: "$type",
mapping: {
Rectangle: "#/components/schemas/Rectangle",
Circle: "#/components/schemas/Circle"
}
}
},
Rectangle: {
type: "object",
allOf: [
{
"$ref": "#/components/schemas/Shape"
}
],
...
},
Circle: {
type: "object",
allOf: [
{
"$ref": "#/components/schemas/Shape"
}
],
...
}
}
} Jika UseAllOfForInheritance atau UseOneOfForPolymorphism diaktifkan, dan dukungan serializer Anda (dan telah diaktifkan) memancarkan/menerima properti diskriminator, maka Swashbuckle akan secara otomatis menghasilkan metadata discriminator yang sesuai pada definisi skema dasar.
Atau, jika Anda telah menyesuaikan serializer Anda untuk mendukung serialisasi/deserialisasi polimorfik, Anda dapat memberikan beberapa fungsi pemilih khusus untuk menentukan nama diskriminator dan pemetaan yang sesuai:
services.addswaggengen (c => {... c.useOneofforinitance (); c.selectdiscriminatornameusing ((Basetype) => "typename"); c.selectdiscriminatorValueusing ((subtipe) => subtype.name);}); Catatan: Jika Anda menggunakan perpustakaan anotasi Swashbuckle, itu berisi fungsi pemilih khusus yang didasarkan pada adanya atribut SwaggerDiscriminator dan SwaggerSubType pada definisi kelas dasar. Dengan cara ini, Anda dapat menggunakan atribut sederhana untuk secara eksplisit menyediakan metadata diskriminator. Untuk mengaktifkan perilaku ini, lihat dokumen anotasi.
Secara default, UI Swagger akan diekspos di "/Swagger". Jika perlu, Anda dapat mengubah ini saat mengaktifkan middleware Swaggerui:
app.useswaggerui (c => {c.RoutePrefix = "API-DOCS"}Secara default, UI Swagger akan memiliki judul dokumen generik. Ketika Anda memiliki beberapa halaman kesombongan terbuka, mungkin sulit untuk membedakannya. Anda dapat mengubah ini saat mengaktifkan middleware Swaggerui:
app.useswaggerui (c => {c.documenttitle = "my swagger ui";}Secara default, UI Swagger termasuk CSS dan JS default, tetapi jika Anda ingin mengubah jalur atau URL (misalnya menggunakan CDN):
app.useswaggerui (c => {c.stylespath = "https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.17.10/swagger-ui.min.min : //cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.17.10/swagger-ui-bundle.min.js "; c.scriptpresetspath =" https://cdnjs.cloudflare.com/ajax/libs /swagger-ui/5.17.10/swagger-ui-standalone-preset.min.js ";}Saat mengaktifkan middleware, Anda diharuskan menentukan satu atau lebih titik akhir kesombongan (sepenuhnya memenuhi syarat atau relatif terhadap halaman UI) untuk memberi daya pada UI. Jika Anda memberikan beberapa titik akhir, mereka akan terdaftar di sudut kanan atas halaman, memungkinkan pengguna untuk beralih di antara dokumen yang berbeda. Misalnya, konfigurasi berikut dapat digunakan untuk mendokumentasikan versi API yang berbeda.
app.useswaggerui (c => {c.swaggerendpoint ("/swagger/v1/swagger.json", "v1 docs"); c.swaggerendpoint ("/Swagger/v2/swagger.json", "v2 docs"); }Kapal Swagger-UI dengan set parameter konfigurasi sendiri, semuanya dijelaskan di sini. Di Swashbuckle, sebagian besar dari ini muncul melalui opsi middleware Swaggerui:
app.useswaggerui (c => {c.DefaultModelExpandDepth (2); c.DefaultModelrendering (ModelRendering.Model); c.DefaultModelsExpandDepth (-1); c.displayOperationId (); c.displayRiBRIBIRATION (); c.disPlayOperationId (); c.displayreuration (); c.disPlayOpenId (); c.displayRiBRIBIRASIRASIRURASIB (); None); [MyCustomplugin "]; ) => {return response;} ");});Catatan
Saat menambahkan plugin khusus, pastikan Anda menambahkan file js khusus yang menentukan fungsi plugin.
Untuk mengubah perilaku, Anda dapat menyuntikkan file JavaScript tambahan dengan menambahkannya ke folder wwwroot Anda dan menentukan jalur relatif dalam opsi middleware:
app.useswaggerui (c => {c.InjectJavAscript ("/Swagger-ui/custom.js");} CATATAN: Opsi InjectOnCompleteJavaScript dan InjectOnFailureJavaScript telah dihapus karena versi terbaru dari Swagger-UI tidak mengekspos kait yang diperlukan. Sebaliknya, ia menyediakan sistem kustomisasi yang fleksibel berdasarkan konsep dan pola dari React dan Redux. Untuk memanfaatkan ini, Anda harus memberikan versi khusus index.html seperti yang dijelaskan di bawah ini.
Aplikasi sampel Indeks Kustom menunjukkan pendekatan ini, menggunakan sistem plugin Swagger-UI menyediakan topbar khusus, dan untuk menyembunyikan komponen info.
Untuk mengubah tampilan dan nuansa, Anda dapat menyuntikkan stylesheet CSS tambahan dengan menambahkannya ke folder wwwroot Anda dan menentukan jalur relatif dalam opsi middleware:
app.useswaggerui (c => {c.Injectstylesheet ("/Swagger-ui/custom.css");}Untuk menyesuaikan UI di luar opsi dasar yang tercantum di atas, Anda dapat memberikan versi Anda sendiri dari SWAGGER-UI Index.html halaman:
app.useswaggerui (c => {c.indexStream = () => getType (). Assembly .getManifestresourcestream ("customuiindex.swagger.index.html"); // membutuhkan file untuk ditambahkan sebagai sumber daya tertanam});Untuk memulai, Anda harus mendasarkan indeks kustom Anda. HTML pada versi default
Swagger-UI memiliki dukungan bawaan untuk berpartisipasi dalam aliran otorisasi OAuth2.0. Ini berinteraksi dengan otorisasi dan/atau titik akhir token, sebagaimana ditentukan dalam Swagger JSON, untuk mendapatkan token akses untuk panggilan API berikutnya. Lihat Menambahkan Definisi dan Persyaratan Keamanan Untuk contoh menambahkan metadata OAuth2.0 ke kesombongan yang dihasilkan.
Jika titik akhir kesombongan Anda mencakup metadata keamanan yang sesuai, interaksi UI harus diaktifkan secara otomatis. Namun, Anda dapat lebih lanjut menyesuaikan dukungan OAuth di UI dengan pengaturan berikut di bawah ini. Lihat Dokumentasi Swagger-UI untuk info lebih lanjut:
app.useswaggerui (c => {c.oauthclientId ("test-id"); c.oauthclientsecret ("test-secret"); c.oauthusername ("Uji-pengguna"); c.oauthrealm ("test-realm" ); String, String> {{"foo", "bar"}});Untuk menggunakan pencegat khusus atas permintaan dan tanggapan yang melalui Swagger-UI Anda dapat mendefinisikannya sebagai fungsi JavaScript dalam konfigurasi:
app.useswaggerui (c => {c.useRequestInterceptor ("(req) => {req.headers ['x-my-custom-header'] = 'mycustomValue'; return req;}"); c.useresponseptor (" (res) => {console.log ('Custom Interceptor Intercepted Response dari:', res.url);Ini dapat berguna dalam berbagai skenario di mana Anda mungkin ingin menambahkan token XSRF lokal ke semua permintaan misalnya:
app.useswaggerui (c => {c.useRequestInterceptor ("(req) => {req.headers ['x-xsrf-token'] = localstorage.getItem ('xsrf-token'); return req;}"); });Instal Paket Nuget berikut ke dalam aplikasi Core ASP.NET Anda.
Package Manager : Install-Package Swashbuckle.AspNetCore.Annotations CLI : dotnet add package Swashbuckle.AspNetCore.Annotations
Dalam metode ConfigureServices Startup.cs , aktifkan anotasi di dalam blok konfigurasi Swagger:
services.addswaggengen (c => {... c.enableannotations ();}); Setelah anotasi diaktifkan, Anda dapat memperkaya metadata operasi yang dihasilkan dengan menghias tindakan dengan SwaggerOperationAttribute .
[Httppost] [SwaggerOperation (ringkasan = "membuat produk baru", description = "membutuhkan hak istimewa admin", operatorid = "createProduct", tags = baru [] {"beli", "produk"})] public iactionResult Buat ([[] Frombody] Produk Produk) ASP.NET Core menyediakan ProducesResponseTypeAttribute untuk mendaftar berbagai respons yang dapat dikembalikan oleh suatu tindakan. Atribut ini dapat dikombinasikan dengan komentar XML, seperti dijelaskan di atas, untuk memasukkan deskripsi ramah manusia dengan setiap respons dalam kesombongan yang dihasilkan. Jika Anda lebih suka melakukan semua ini dengan satu atribut, dan menghindari penggunaan komentar XML, Anda dapat menggunakan SwaggerResponseAttribute S sebagai gantinya:
[Httppost] [SwaggerResponse (201, "Produk Diciptakan", TipeOf (Produk))] [SwaggerResponse (400, "Data Produk tidak valid")] PUBLIC IACKICTRESULT membuat (frombody] produk produk)
Anda dapat memberi anotasi "jalur", "kueri" atau "header" parameter atau properti terikat (yaitu dihiasi dengan [FromRoute] , [FromQuery] atau [FromHeader] ) dengan SwaggerParameterAttribute untuk memperkaya metadata Parameter yang sesuai yang dihasilkan oleh swashbuckle:
[Httpget] public iactionResult getProducts ([fromquery, swaggerparameter ("kata kunci pencarian", diperlukan = true)] kata kunci string) Anda dapat memberi anotasi parameter atau properti terikat "tubuh" (yaitu didekorasi dengan [FromBody] ) dengan SwaggerRequestBodyAttribute untuk memperkaya metadata RequestBody yang sesuai yang dihasilkan oleh swashbuckle:
[Httppost] public iactionResult createProduct ([dari Body, SwaggerRequestBody ("The Product Payload", wajib = true)] Produk Produk) Anda dapat memberi anotasi kelas atau properti dengan SwaggerSchemaAttribute untuk memperkaya metadata Schema yang sesuai yang dihasilkan oleh Swashbuckle:
[Swaggerschema (wajib = baru [] {"deskripsi"})] Produk kelas publik {[Swaggerschema ("Pengidentifikasi Produk", ReadOnly = true)] public int id {get; mengatur; } [Swaggerschema ("Deskripsi Produk")] Deskripsi String Publik {get; mengatur; } [Swaggerschema ("tanggal itu dibuat", format = "date")] datetime public datecreated {get; mengatur; }} Catatan: Dalam Swagger / OpenAPI, objek serial dan properti yang terkandung diwakili sebagai instance Schema , karenanya mengapa anotasi ini dapat diterapkan pada kelas dan properti. Juga patut dicatat, properti "wajib" ditentukan sebagai berbagai nama properti pada skema tingkat atas yang bertentangan dengan bendera pada setiap properti individu.
Paket SwaggerGen menyediakan beberapa titik ekstensi, termasuk filter skema (dijelaskan di sini) untuk menyesuaikan semua skema yang dihasilkan. Namun, mungkin ada kasus di mana lebih disukai untuk menerapkan filter ke skema tertentu. Misalnya, jika Anda ingin memasukkan contoh untuk jenis tertentu dalam API Anda. Ini dapat dilakukan dengan mendekorasi tipe dengan SwaggerSchemaFilterAttribute :
// Product.cs [SwaggersChemAfilter (typeOf (ProductChemAfilter))] Produk kelas publik {...} // ProductChemAfilter.cspublic ProductChemAfilter: IschemAfilter {public void apply (OpenapisChema schema, schemaFilterContext Context {schema. schema. Schema. Schema. Schema. Schema. Schema. Schema. Schema. Schema. Schema. Schema. SCHEMAFILTEXTEX ["Id"] = Openapiinteger baru (1), ["deskripsi"] = Openapistring baru ("produk yang luar biasa")};}} Secara default, generator Swagger akan menandai semua operasi dengan nama pengontrol. Tag ini kemudian digunakan untuk mengarahkan pengelompokan operasi di Swagger-UI. Jika Anda ingin memberikan deskripsi untuk masing -masing grup ini, Anda dapat melakukannya dengan menambahkan metadata untuk setiap tag nama pengontrol melalui SwaggerTagAttribute :
[Swaggertag ("Buat, Baca, Perbarui dan Hapus Produk")] Produk Kelas Publik Controller {...} Catatan: Ini akan menambahkan deskripsi di atas secara khusus ke tag bernama "Produk". Oleh karena itu, Anda harus menghindari menggunakan atribut ini jika Anda menandai operasi dengan sesuatu selain nama pengontrol - misalnya jika Anda menyesuaikan perilaku penandaan dengan TagActionsBy .
Jika Anda ingin menggunakan perilaku warisan dan/atau polimorfisme Swashbuckle, Anda dapat menggunakan anotasi untuk secara eksplisit menunjukkan subtipe "yang diketahui" untuk jenis dasar yang diberikan. Ini akan mengganti fungsi pemilih default, yang memilih semua subtipe dalam perakitan yang sama dengan jenis dasar, dan karenanya perlu diaktifkan secara eksplisit ketika Anda mengaktifkan anotasi:
// startup.csservices.addswaggergen (c => {c.enableannotations (enableAnnotationsForinitance: true, enableAnnotationsForpolymorphism: true);}); // shape.cs [swaggersubtype (typeof (rectangle))] [swaggerse [swaggersubtype (typeof (rectangle))] [swaggerse [swaggersubtype (typeOf (rectangle))] [swaggers) [swaggersubtype (typeOf (rectangle))]] [swagger ] Bentuk kelas abstrak publik {} Jika Anda menggunakan anotasi untuk secara eksplisit menunjukkan subtipe "yang diketahui" untuk tipe dasar polimorfik, Anda dapat menggabungkan SwaggerDiscriminatorAttribute dengan SwaggerSubTypeAttribute untuk memberikan metadata tambahan tentang properti "diskriminator", yang kemudian akan dimasukkan ke dalam definisi skema yang dihasilkan:
// startup.csservices.addswaggengen (c => {c.enableannotations (enableAnnotations forinitance: true, enableannotationsForpolymorphism: true);}); // bentuk.cs [swaggingcriminator ("shapetype")] [Swaggers (swagyple ("shapeType")] [swaggers ("shapeType")] [swaggers ("shapeType")] [swaggers ("shapetype")] = "persegi panjang")] [SwaggersubType (typeof (lingkaran), diskriminatorValue = "lingkaran")] bentuk kelas abstrak publik {public shapetype {get; mengatur; }} Ini menunjukkan bahwa muatan yang sesuai akan memiliki properti "shapetype" untuk membedakan antara subtipe, dan properti itu akan memiliki nilai "persegi panjang" jika muatan mewakili jenis Rectangle dan nilai "lingkaran" jika mewakili jenis Circle . Detail ini akan dijelaskan dalam definisi skema yang dihasilkan sebagai berikut:
schema: {
oneOf: [
{
$ref: "#/components/schemas/Rectangle"
},
{
$ref: "#/components/schemas/Circle"
},
],
discriminator: {
propertyName: shapeType,
mapping: {
rectangle: "#/components/schemas/Rectangle",
circle: "#/components/schemas/Circle",
}
}
}Setelah aplikasi Anda diatur dengan Swashbuckle (lihat memulai), Anda dapat menggunakan alat CLI Swashbuckle untuk mengambil Swagger / Openapi Json langsung dari perakitan startup aplikasi Anda, dan menulisnya untuk mengajukan. Ini bisa berguna jika Anda ingin memasukkan generasi kesombongan ke dalam proses CI/CD, atau jika Anda ingin menyajikannya dari file statis saat run-time.
Ini dikemas sebagai alat .net yang dapat diinstal dan digunakan melalui Dotnet SDK.
️ Alat ini perlu memuat DLL startup Anda dan ketergantungannya saat runtime. Oleh karena itu, Anda harus menggunakan versidotnetSDK yang kompatibel dengan aplikasi Anda. Misalnya, jika aplikasi Anda menargetkannet6.0, maka Anda harus menggunakan versi 6.0.xxx dari SDK untuk menjalankan alat CLI. Jika menargetkannet8.0, maka Anda harus menggunakan versi 8.0.xxx dari SDK dan sebagainya.
Instal sebagai alat global
dotnet tool install -g Swashbuckle.AspNetCore.Cli
Verifikasi bahwa alat tersebut diinstal dengan benar
swagger tofile --help
Hasilkan Dokumen Kesombongan/ OpenAPI dari Majelis Startup Aplikasi Anda
swagger tofile --output [output] [startupassembly] [swaggerdoc]
Di mana ...
[output] adalah jalur relatif di mana Swagger JSON akan menjadi output
[StartupAssembly] adalah jalur relatif ke perakitan startup aplikasi Anda
[SwaggerDoc] adalah nama dokumen Swagger yang ingin Anda ambil, seperti yang dikonfigurasi di kelas startup Anda
Di root proyek Anda, buat file manifes alat:
dotnet new tool-manifest
Instal sebagai alat lokal
dotnet tool install Swashbuckle.AspNetCore.Cli
Verifikasi bahwa alat tersebut diinstal dengan benar
dotnet swagger tofile --help
Hasilkan Dokumen Kesombongan / OpenAPI dari Majelis Startup Aplikasi Anda
dotnet swagger tofile --output [output] [startupassembly] [swaggerdoc]
Di mana ...
[output] adalah jalur relatif di mana Swagger JSON akan menjadi output
[StartupAssembly] adalah jalur relatif ke perakitan startup aplikasi Anda
[SwaggerDoc] adalah nama dokumen Swagger yang ingin Anda ambil, seperti yang dikonfigurasi di kelas startup Anda
Di luar kotak, alat ini akan dieksekusi dalam konteks host web "default". Namun, dalam beberapa kasus Anda mungkin ingin membawa lingkungan host Anda sendiri, misalnya jika Anda telah mengonfigurasi wadah DI khusus seperti AUTOFAC. Untuk skenario ini, alat CLI Swashbuckle memperlihatkan kait berbasis konvensi untuk aplikasi Anda.
Artinya, jika aplikasi Anda berisi kelas yang memenuhi salah satu dari konvensi penamaan berikut, maka kelas itu akan digunakan untuk menyediakan host untuk dilakukan oleh alat CLI.
public class SwaggerHostFactory , berisi metode statis publik yang disebut CreateHost dengan tipe pengembalian IHost
public class SwaggerWebHostFactory , berisi metode statis publik yang disebut CreateWebHost dengan tipe pengembalian IWebHost
Misalnya, kelas berikut dapat digunakan untuk memanfaatkan konfigurasi host yang sama dengan aplikasi Anda:
Public Class SwaggerHostFactory {public static ihost createHost () {return program.createHostBuilder (string baru [0]). build ();}}Secara default, REDOC UI akan diekspos pada "/API-DOCS". Jika perlu, Anda dapat mengubah ini saat mengaktifkan middleware redoc:
app.useredoc (c => {c.routePrefix = "docs" ...}Secara default, REDOC UI akan memiliki judul dokumen generik. Anda dapat mengubah ini saat mengaktifkan middleware redoc:
app.useredoc (c => {c.documenttitle = "My API docs"; ...}Redoc mengirim dengan set parameter konfigurasi sendiri, semuanya dijelaskan di sini https://github.com/rebilly/redoc/blob/main/readme.md#redoc-options-object. Di Swashbuckle, sebagian besar dari ini muncul melalui opsi middleware redoc:
app.useredoc (c => {c.specurl ("/v1/swagger.json"); c.EnableUntrustedspec (); c.scrollyoffset (10); c.hidehostname (); c.hidedownloadbutton (); c.expandresponsses (200.201 "); Sortpropsalphabetically ();}); Menggunakan c.SpecUrl("/v1/swagger.json") beberapa kali dalam UseReDoc(...) tidak akan menambahkan beberapa URL.
Untuk mengubah tampilan dan nuansa, Anda dapat menyuntikkan stylesheet CSS tambahan dengan menambahkannya ke folder wwwroot Anda dan menentukan jalur relatif dalam opsi middleware:
app.useredoc (c => {... c.Injectstylesheet ("/redoc/custom.css");} Dimungkinkan juga untuk memodifikasi tema dengan menggunakan properti AdditionalItems , lihat https://github.com/rebilly/redoc/blob/main/readme.md#redoc-options-Object untuk informasi lebih lanjut.
app.useredoc (c => {... c.configObject.additionalitems = ...}Untuk menyesuaikan UI di luar opsi dasar yang tercantum di atas, Anda dapat memberikan versi Anda sendiri dari redoc index.html halaman:
app.useredoc (c => {c.indexStream = () => getType (). Assembly .getManifestresourcestream ("customIndex.redoc.index.html"); // membutuhkan file untuk ditambahkan sebagai sumber daya tertanam});Untuk memulai, Anda harus mendasarkan indeks kustom Anda. HTML pada versi default
