Dokumen antarmuka eksternal selalu relatif primitif, dan pada dasarnya dokumen tulisan tangan dilewatkan. Baru -baru ini, saya menemukan mainan baru, yang dapat menghemat banyak masalah di antarmuka.
Swagger adalah kerangka dokumentasi API yang nyaman. Ini dapat menampilkan tipe antarmuka ke pengembang lain dengan cara yang paling komprehensif, menghindari perilaku satu sisi dan kesalahan dokumen tulisan tangan.
Saat ini ada dua jenis kesombongan dan kesombongan2. 1 lebih merepotkan, jadi Anda tidak mempertimbangkan untuk menggunakannya. Artikel ini terutama mencatat dua cara saya menggunakan Swagger2 sebagai antarmuka eksternal. Silakan periksa nanti.
1. Gunakan SpringMVC tradisional untuk mengintegrasikan Swagger2
1. Ketergantungan Maven
<!-Dependensi Springfox-> <dependency> <groupid> com.fasterxml.jackson.core </groupid> <Artifactid> jackson-core </t Artifactid> <version> 2.8.0 </version> </ArtiCid> <ArtaciD> <Rouptid> com.fasterxml.jackson.core> </groupid> <grouptid> <Rouptid> JACKSOND.JACKSON.CORE> <Version> 2.6.3 </version> </gandendency> <dependency> <groupid> com.fasterxml.jackson.core </groupid> <Artifactid> Jackson-annotations </StifactId> <Version> 2.6.3 </version> </dependency> <grouppid> <groupdid> IO.SPRINGFOX </Versi> </dependency> <grouptid> <grouppid> <version> 2.4.0 </version> </dependency> <dependency> <GroupId> io.springfox </groupid> <ArTifactId> springfox-swagger-ui </artifactid> <version> 2.4.0 </version> </ketergantungan>
2. Tambahkan konfigurasi pemetaan statis di spring-mvc.xml (sebenarnya, saya dapat menghapus ini dalam proyek saya, saya tidak tahu apa situasinya):
<!-jalur file statis Swagger-> <mvc: sumber daya lokasi = "classpath:/meta-inf/sumber daya/" pemetaan = "swagger-ui.html"/> <mvc: sumber daya lokasi = "classpath:/meta-inf/sumber daya/webjars/" pemetaan = "/webjars/**"/>
Catatan: Saya tidak akan memposting konfigurasi SpringMVC dasar. Perlu dicatat bahwa jika Anda melihat antarmuka Swagger-ui.html keluar, tetapi kosong, silakan periksa konfigurasi pencegat di web.xml Anda. Anda harus mencegat springmvc terlebih dahulu, dan kemudian antarmuka akan ditampilkan.
3. Lalu ada kelas konfigurasi Swagger2:
@Configuration @enableSwagger2public kelas SwaggerConfig memperluas webmvcconfigurationsupport {@bean docket publik createrestapi () {return new docket (documentationType.swagger_2) .ApiInfo (ApiInfo ()) .select () .apis (requestLerSelecors.boYFo (ApiInfo ()) .select () .apis (requestLerSelecors.baPuy () .derselecor () .pislekor () .apis.piLeclecors. .paths (pathselectors.any ()) .build (); } private apiInfo apiInfo () {return new ApiInfobuilder () .title ("YYBLOG Project Restful API") .Description ("Dokumentasi Antarmuka API Proyek YYBLOG") .Version ("1.0") .build (); }}Catatan: Jika jalur dapat disesuaikan dengan PathSelectors.none () dalam produksi, itu tidak menampilkan semua informasi antarmuka;
4. Konfigurasi Informasi Antarmuka
Yaitu, konfigurasikan informasi antarmuka yang relevan di controller springmvc
@Controller@requestMapping (value = "AITOU")@API (description = "Test Layanan-Akun Informasi Permintaan") Kelas Publik DailyOperationDataController {Logger Logger = Logger.getLogger (DailyOperationDataController.class); @Autowired Private DailyOperationDataService DailyOperationService; / * * @ApiOperation (value = "Deskripsi Antarmuka", httpmethod = "Metode Permintaan Antarmuka", Respons = "Jenis Parameter Pengembalian Antarmuka", Catatan = "Catatan Rilis Antarmuka" * @Apiparam (Diperlukan = "adalah parameter yang diperlukan", name = "nama parameter", nilai query @(value) @Parameter Uraian Parameter ") (value =" name = "Parameter Name", Value = "Parameter spesifik deskripsi" */ @Apioperation (value = "Parameter Name", Nilai Parameter (Nilai Parameter (Value ") (Value =" Value = "Value" (Value "(Value" (Value "(Value" (Value ") Parameter spesifik") (value = "value =" name "name @ @paramace @) = {RequestMethod.post, requestMethod.get}, value = "/query/dailydata/{datadate}") @ResponseBody public dailyOperationDataDTo getDailyreportByDataDate (@pathvariable ("dataDate") string datadate) {try {return dailyOporation) DATREATEAD ("DATADATE") DATADATE) {try {return dailyOporation) } catch (Exception e) {Logger.Error (E.GetMessage (), E);Catatan: Biasanya, Swagger2 akan menampilkan semua antarmuka di bawah paket pemindaian. Di sini saya adalah antarmuka eksternal untuk menjadi paket terpisah untuk menghindari menampilkan terlalu banyak antarmuka. Tentu saja, metode antarmuka juga dapat mencegahnya menampilkan. Anda dapat melihat anotasi yang relevan di bawah ini.
Beberapa catatan yang biasa digunakan
@Api: digunakan pada kelas untuk menggambarkan fungsi kelas
@Apioperation: digunakan dalam metode untuk menggambarkan fungsi metode
@ApIImplicitParams: Digunakan untuk memasukkan satu set deskripsi parameter pada metode ini
@ApIImplicitParam: Digunakan dalam anotasi @ApIImplicitParams, tentukan berbagai aspek parameter parameter permintaan: di mana menempatkan parameter ・ header -> Dapatkan parameter permintaan: @Requestheader
・ Kueri -> Permintaan Parameter Akuisisi: @RequestParam
・ Jalur (untuk antarmuka yang tenang) -> mendapatkan parameter permintaan: @pathvariable
・ Tubuh (tidak biasa digunakan)
・ Bentuk (tidak biasa digunakan)
Nama: Nama Parameter DataType: Parameter Jenis Diperlukan: Apakah parameter harus diteruskan nilai: parameter makna defaultValue: parameter nilai default
@Apirespons: digunakan untuk mewakili serangkaian tanggapan
@Apiresponse: digunakan dalam @apirespons, umumnya digunakan untuk mengekspresikan kode respons kesalahan: angka, seperti 400
Pesan: Pesan, seperti "parameter permintaan tidak diisi"
Tanggapan: Kelas yang melempar pengecualian
@Apiparam: Deskripsi parameter tunggal
@Apimodel: Jelaskan informasi model dan gunakan objek untuk menerima parameter (ini biasanya digunakan saat membuat posting, menggunakan skenario @Requestbody, dan saat meminta parameter tidak dapat dijelaskan menggunakan anotasi @ApiImplicitParam)
@Apimodelproperty: Jelaskan sifat -sifat model
@ApipRoperty: Saat menggunakan objek untuk menerima parameter, jelaskan bidang objek
@Apiignore: Gunakan anotasi ini untuk mengabaikan API ini
Pada dasarnya, semuanya di atas. Bukankah itu sangat mudah? Mari kita lihat gambar efeknya di bawah ini
2. Gunakan Springboot untuk mengintegrasikan Swagger2
Di atas disebutkan menggunakan springmvc tradisional untuk mengintegrasikan Swagger2. Mari kita bicara tentang metode springboot populer terbaru. Faktanya, prinsip -prinsipnya sama.
1. Ketergantungan Maven
<!-Dependensi Springfox-> <dependency> <GroupId> io.springfox </groupid> <ArtifactId> springfox-swagger2 </arttifactid> <version> 2.7.0 </version> </dependency> <grouptid> io.springfox </groupid> <t Artifact> <version> 2.7.0 </version> </gantisan>
Ini adalah penggunaan internal dari proyek pribadi saya yang saya tulis baru -baru ini menggunakan Springboot, dan versi yang digunakan 2.7.0 digunakan dalam versi tersebut.
2. Tambahkan Konfigurasi Sumber Daya Statis
@ConfigurationPublic kelas webmvcconfig memperluas webmvcconfigurerAdapter {/ ** * Konfigurasikan jalur sumber daya statis dan jalur untuk mengunggah file * * @param registry */ @override void addResourceHandlers (ResourceHandlegistry Registry) {@Override void addResourceHandlers (ResourceHandLegistry Registry) { Registry.addResourceHandler ("/static/**"). AddResourcelocations ("classpath:/static/"); Registry.addResourceHandler ("/unggah/**"). AddResourcelocations (Environment.getProperty ("Spring.Resources.Static-Locations")); /*Swagger-ui*/Registry.addResourceHandler ("Swagger-ui.html"). AddResourcelocations ("ClassPath:/Meta-Inf/Resources/"); Registry.addResourceHandler ("/WebJars/**"). AddResourcelocations ("ClassPath:/Meta-Inf/Resources/Webjars/"); }}Bahkan, itu hanya dua kalimat terakhir. Jika Anda tidak mengkonfigurasi ini, Anda akan melihat kesalahan 500 atau 404 saat Anda mengunjungi Swagger-ui.html. Jika Anda tidak dapat mengingatnya, itu harus 404.
3. Kelas Konfigurasi Swagger2
Seperti halnya di atas, pada dasarnya tidak ada perbedaan
@Configuration@enableSwagger2@enableWebMvcpublic class swaggerconfig memperluas webmvccconfigurationsupport {@bean public docket createrestapi () {return new dapet (documentationType.swagger_2) .apiInfo (apiInfo () .select () .apis (requesthandlerselectors.basepackage ("net.laoyeye.yyblog.web.frontend")) .paths (pathselectors.none ()) .build (); } private apiInfo apiInfo () {return new ApiInfoBuilder () .title ("YYBLOG Project Restful API") .Description ("Dokumen Antarmuka API Proyek YYBLOG") .Version ("1.0") .build (); }}Perhatikan bahwa saya memiliki masalah dengan jalur di atas. Salinan secara langsung tidak menampilkan API (#^.^#)
4. Konfigurasi Antarmuka
/*** Pengendali Artikel Meja Depan* @Author Grandpa di toko serba ada* @Date 5 Mei 2018* @website www.laoyeye.net*/ @API (deskripsi = "Query artikel") @controller @requestMapping ("/artikel") Articlecontroller {@AroWirired prajurit; @Autowired Private SettingService SettingService; @Autowired Private Cateservice Cateservice; @Autowired private tagerservice tagreferservice; @Autowired Private UserServerServiceService; @Autowired Private Articlemapper Articlemapper; @Autowired Private -Commentservice Commentservice; @ApiOperation (value = "Antarmuka Artikel Query") @ApIImplicitParam (name = "id", value = "Article ID", wajib = true, DataType = "long") @getMapping ("/{id}") indeks string publik (model model, @pathvariable ("id") ID long) {try {articleservice. } catch (pengecualian abaikan) {} Daftar <SITED> Pengaturan = SettingService.Listall (); Peta <string, object> peta = hashmap baru <string, object> (); untuk (pengaturan pengaturan: pengaturan) {map.put (pengaturan.getCode (), pengaturan.getValue ()); } Artikel artikel = artikelService.getarticleById (id); model.addattribute ("Pengaturan", peta); model.addattribute ("Catelist", CategoryService.ListAllCate ()); model.addattribute ("artikel", artikel); model.addattribute ("tag", tagreferservice.listnamebyarticleid (artikel.getId ())); model.addattribute ("penulis", UsserService.getNickNamebyId (artikel.getauthorid ())); // ubah model.addattribute ("artikel", articlemapper.listarticleByTitle (null)); model.addattribute ("serupa", articlemapper.listarticleByTitle (null)); Query commentQuery = commentQuery baru (); query.setlimit (10); query.setPage (1); query.setarticleid (id); model.addattribute ("Comments", CommentService.ListCommentByarticleId (Query)); mengembalikan "frontend/artikel"; } @ApiOperation (value = "Antarmuka ArticLecomment Query") @PostMapping ("/Comments") @ResponseBody Public DatagridResult Komentar (kueri CommentQuery) {// Atur default 10 query.setlimit (10); return commentservice.listCommentByarticleId (kueri); } @ApiOperation(value="ArticleLid") @ApiImplicitParam(name = "articleId", value = "ArticleID", required = true, dataType = "Long") @PostMapping("/approve") @ResponseBody public YYBlogResult approve(@RequestParam Long articleId) { return articleService.updateApproveCntById(articleId); }}Akhirnya, ada rendering, sama seperti di atas.
Ketika pathselectors.none () adalah
Ketika pathselectors.any () adalah
Jelas sekali apakah konten antarmuka adalah rendering, dan sangat ringkas dan jelas.
Akhirnya, sepertinya saya lupa mengatakan jalan menuju dokumen kesombongan
Jika proyek Anda ada di direktori root: http: // localhost: 8080/swagger-ui.html
Jika bukan direktori root, itu adalah: http: // localhost: 8080/nama proyek Anda/Swagger-ui.html
Di atas adalah semua konten artikel ini. Saya berharap ini akan membantu untuk pembelajaran semua orang dan saya harap semua orang akan lebih mendukung wulin.com.