เอกสารอินเทอร์เฟซภายนอกนั้นค่อนข้างดั้งเดิมอยู่เสมอและเอกสารที่เขียนด้วยลายมือโดยทั่วไปจะถูกส่งผ่าน เมื่อเร็ว ๆ นี้ฉันค้นพบของเล่นใหม่ซึ่งสามารถบันทึกปัญหามากมายในอินเทอร์เฟซ

Swagger เป็นกรอบเอกสาร API ที่สะดวก มันสามารถแสดงประเภทอินเทอร์เฟซให้กับนักพัฒนาอื่น ๆ ในวิธีที่ครอบคลุมที่สุดหลีกเลี่ยงพฤติกรรมด้านเดียวและข้อผิดพลาดของเอกสารที่เขียนด้วยลายมือ

ปัจจุบันมีสองประเภทของ swagger และ swagger2 1 เป็นปัญหามากขึ้นดังนั้นคุณจึงไม่พิจารณาใช้มัน บทความนี้ส่วนใหญ่บันทึกสองวิธีที่ฉันใช้ Swagger2 เป็นอินเทอร์เฟซภายนอก โปรดตรวจสอบในภายหลัง

1. ใช้ SpringMVC แบบดั้งเดิมเพื่อรวม swagger2

1. การพึ่งพา Maven

 <!-การพึ่งพา SpringFox-> <predency> <sdeperency> <sdeperency> <roupId> com.fasterxml.jackson.core </groupId> <ratifactid> Jackson-Core </artifactid> <version> 2.8.0 </เวอร์ชัน> </การพึ่งพา> <Sersion> 2.6.3 </Servive> </perdency> <การพึ่งพา> <roupId> com.fasterxml.jackson.core </groupId> <ratifactid> Jackson-Annotations </artifactId> <version> 2.6.3 </เวอร์ชัน> <ArtIfactId> SpringFox-Swagger2 </artifactId> <sersion> 2.4.0 </Side> </การพึ่งพา> <การพึ่งพา> <GroupId> io.springfox </groupId>

2. เพิ่มการกำหนดค่าการแมปแบบคงที่ใน Spring-MVC.XML (จริง ๆ แล้วฉันสามารถลบสิ่งนี้ในโครงการของฉันฉันไม่รู้ว่าสถานการณ์คืออะไร):

 <!-เส้นทางไฟล์คงที่ swagger-> <mvc: แหล่งข้อมูลตำแหน่ง = "classpath:/meta-inf/resources/" mapping = "swagger-ui.html"/> <mvc: แหล่งข้อมูล = "classpath:/meta-inf/resources/webjars/" mapping = "/webjars/**

หมายเหตุ: ฉันจะไม่โพสต์การกำหนดค่า SpringMVC พื้นฐาน ควรสังเกตว่าหากคุณเห็นอินเทอร์เฟซ Swagger-ui.html ออกมา แต่ว่างเปล่าโปรดตรวจสอบการกำหนดค่าของ interceptor ใน web.xml ของคุณ คุณต้องสกัดกั้น SpringMVC ก่อนจากนั้นอินเทอร์เฟซจะแสดง

3. จากนั้นมีคลาสการกำหนดค่าของ Swagger2:

 @configuration @enablewagger2public คลาส SwaggerConfig ขยาย webmvcconfigurationsupport {@bean public docket createrestapi () {ส่งคืนใบปะหน้าใหม่ .APIS (requesthandlerselectors.basepackage ("net.laoyeyey.yyblog")) .paths (pathselectors.any ()) .build (); } ส่วนตัว apiinfo apiinfo () {ส่งคืน apiinfobuilder ใหม่ () .title ("yyblog Project RESTful APIs") .Description ("Yyblog Project API Interface Documentation") .Version ("1.0") .build (); -

หมายเหตุ: หากเส้นทางสามารถปรับให้เข้ากับ pathSelectors.none () ในการผลิตมันจะไม่แสดงข้อมูลส่วนต่อประสานทั้งหมด

4. การกำหนดค่าข้อมูลอินเตอร์เฟส

นั่นคือกำหนดค่าข้อมูลอินเทอร์เฟซที่เกี่ยวข้องในคอนโทรลเลอร์ SpringMVC

 @controller@requestmapping (value = "aitou")@api (คำอธิบาย = "สอบถามข้อมูลการใช้บริการบัญชีสาธารณะ") ชั้นเรียนสาธารณะ DailyOperationDataController {logger logger = logger.getLogger (DailyOperationDataController.class); @autowired ส่วนตัว DailyOperationDataservice DailyOperationDataservice; / * * @apioperation (value = "คำอธิบายอินเตอร์เฟส", httpmethod = "วิธีการขออินเตอร์เฟส", response = "ประเภทพารามิเตอร์การส่งคืนอินเตอร์เฟส", notes = "อินเตอร์เฟสรีลีสรีลีส" * @apiparam (จำเป็น = "เป็นพารามิเตอร์ที่จำเป็น", name = "parameter name", value = "คำอธิบายเฉพาะ = {requestMethod.post, requestMethod.get}, value = "/query/dailyData/{datadate}") @ResponSebody สาธารณะ DailyOperationDatadto getDailyReportByDatadate (@PathVariable ("datadate") (ข้อยกเว้น e) {logger.error (e.getMessage (), e);

หมายเหตุ: โดยปกติ Swagger2 จะแสดงอินเทอร์เฟซทั้งหมดภายใต้แพ็คเกจสแกน ที่นี่ฉันเป็นอินเทอร์เฟซภายนอกที่จะเป็นแพ็คเกจแยกต่างหากเพื่อหลีกเลี่ยงการแสดงอินเทอร์เฟซมากเกินไป แน่นอนว่าวิธีการอินเตอร์เฟสยังสามารถป้องกันไม่ให้แสดง คุณสามารถดูคำอธิบายประกอบที่เกี่ยวข้องด้านล่าง

โน้ตที่ใช้กันทั่วไปบางส่วน

@API: ใช้ในคลาสเพื่อแสดงฟังก์ชั่นของคลาส
@apioperation: ใช้ในวิธีการเพื่อแสดงฟังก์ชั่นของวิธีการ
@apiimplicitparams: ใช้เพื่อรวมชุดของคำอธิบายพารามิเตอร์เกี่ยวกับวิธีการ
@apiimplicitparam: ใช้ในคำอธิบายประกอบ @apiimplicitparams, ระบุแง่มุมต่าง ๆ ของพารามิเตอร์การร้องขอพารามิเตอร์ parametype: สถานที่ที่จะวางพารามิเตอร์ ・ ส่วนหัว -> รับพารามิเตอร์คำขอ: @requestheader
・ Query -> การขอพารามิเตอร์การขอ: @requestparam
・ PATH (สำหรับ RESTful Interface) -> รับพารามิเตอร์คำขอ: @PathVariable
・ ร่างกาย (ไม่ได้ใช้กันทั่วไป)
・ แบบฟอร์ม (ไม่ได้ใช้กันทั่วไป)
ชื่อ: พารามิเตอร์ชื่อข้อมูล: ประเภทพารามิเตอร์ที่ต้องการ: ไม่ว่าพารามิเตอร์จะต้องผ่านค่า: พารามิเตอร์หมายถึงค่าเริ่มต้นค่าเริ่มต้น: พารามิเตอร์ค่าเริ่มต้น
@apiresponses: ใช้เพื่อแสดงชุดคำตอบ
@apiresponse: ใช้ใน @apiresponses โดยทั่วไปจะใช้เพื่อแสดงรหัสการตอบกลับข้อผิดพลาด: ตัวเลขเช่น 400
ข้อความ: ข้อความเช่น "พารามิเตอร์คำขอไม่ได้กรอก"
การตอบสนอง: คลาสที่ทำให้เกิดข้อยกเว้น
@Apiparam: คำอธิบายพารามิเตอร์เดียว
@Apimodel: อธิบายข้อมูลของโมเดลและใช้วัตถุเพื่อรับพารามิเตอร์ (โดยปกติจะใช้เมื่อสร้างโพสต์โดยใช้สถานการณ์ @requestbody และเมื่อขอพารามิเตอร์ไม่สามารถอธิบายได้
@ApimodelProperty: อธิบายคุณสมบัติของโมเดล
@apiproperty: เมื่อใช้วัตถุเพื่อรับพารามิเตอร์อธิบายฟิลด์ของวัตถุ
@apiignore: ใช้คำอธิบายประกอบนี้เพื่อเพิกเฉยต่อ API นี้

โดยพื้นฐานแล้วมันคือทั้งหมดข้างต้น มันไม่ง่ายมากเหรอ? มาดูภาพเอฟเฟกต์ด้านล่าง

2. ใช้ Springboot เพื่อรวม Swagger2

ดังกล่าวข้างต้นโดยใช้ SpringMVC แบบดั้งเดิมเพื่อรวม Swagger2 มาพูดคุยเกี่ยวกับวิธีสปริงบู๊ตยอดนิยมล่าสุด ในความเป็นจริงหลักการเหมือนกัน

1. การพึ่งพา Maven

 <!-การพึ่งพา SpringFox-> <การพึ่งพา> <roupId> io.springfox </groupId> <ratifactId> SpringFox-Swagger2 </artifactid> <sversion> 2.7.0 </เวอร์ชัน> <Sersion> 2.7.0 </Sention> </derctency>

นี่คือการใช้งานภายในของโครงการส่วนตัวของฉันที่ฉันเขียนเมื่อเร็ว ๆ นี้โดยใช้ Springboot และรุ่นที่ใช้ 2.7.0 ใช้ในเวอร์ชัน

2. เพิ่มการกำหนดค่าทรัพยากรแบบคงที่

 @ConfigurationPublic คลาส WebMVCCONFIG ขยาย WebMVCCONFigurerAdapter {/ ** * กำหนดค่าเส้นทางทรัพยากรคงที่และเส้นทางในการอัปโหลดไฟล์ * * @Param Registry */ @Override โมฆะสาธารณะ addResourceHandlers registry.addresourceHandler ("/static/**"). addResourceLocations ("classpath:/static/"); registry.addresourceHandler ("/อัปโหลด/**"). 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/"); -

ในความเป็นจริงมันเป็นเพียงสองประโยคสุดท้าย หากคุณไม่ได้กำหนดค่าสิ่งนี้คุณจะเห็นข้อผิดพลาด 500 หรือ 404 เมื่อคุณเยี่ยมชม Swagger-ui.html หากคุณจำไม่ได้ว่าควรเป็น 404

3. คลาสการกำหนดค่า Swagger2

เช่นเดียวกับข้างต้นไม่มีความแตกต่าง

 @configuration@enablewagger2@enablewebmvcpublic คลาส Swaggerconfig ขยาย webmvcconfigurationsupport {@bean public Docket Createrestapi () {ส่งคืนใบปะหน้าใหม่ .Apis (requesthandlerselectors.basepackage ("net.laoyeye.yyblog.web.frontend")) .paths (pathselectors.none ()) .build (); } ส่วนตัว apiinfo apiinfo () {ส่งคืน apiinfobuilder ใหม่ () .title ("yyblog Project RESTful APIs") .Description ("Yyblog Project API Interface Document") .Version ("1.0") .build (); -

โปรดทราบว่าฉันมีปัญหากับเส้นทางด้านบน สำเนาโดยตรงไม่แสดง API (#^.^#)

4. การกำหนดค่าอินเตอร์เฟส

 /*** Controller แผนก Front Desk* @author Grandpa ในร้านสะดวกซื้อ* @date 5 พฤษภาคม 2018* @website www.laoyeye.net*/ @api (คำอธิบาย = "บทความสอบถาม") @controller @requestmapping ("/บทความ") @autowired Settingservice Settingservice; @Autowired Cateservice Cateservice; @autowired Tagreferservice Tagreferservice; @AutoWired Userservice Userservice; @autowired Articlemapper Articlemapper; @autowired Private Commentialervice Commentialervice; @apioperation (value = "บทความการสอบถามอินเทอร์เฟซ") @apiimplicitparam (name = "id", value = "id id id", ต้องการ = true, datatype = "long") @getMapping ("/{id}") ดัชนีสตริงสาธารณะ } catch (ข้อยกเว้นละเว้น) {} รายการ <การตั้งค่า> การตั้งค่า = settingservice.listall (); แผนที่ <string, Object> map = new hashmap <string, object> (); สำหรับ (การตั้งค่าการตั้งค่า: การตั้งค่า) {map.put (การตั้งค่า. getCode (), sett.get.getValue ()); } บทความบทความ = articleservice.getarticleById (id); model.addattribute ("การตั้งค่า", แผนที่); model.addattribute ("catelist", categoryservice.listallcate ()); model.addattribute ("บทความ", บทความ); model.addattribute ("Tags", tagreferservice.listnameByarticleId (article.getId ())); model.addattribute ("ผู้แต่ง", userservice.getNickNameById (article.getauthorid ())); // เปลี่ยนโมเดล AdDattribute ("บทความ", articlemapper.listarticleBytitle (null)); model.addattribute ("คล้ายกัน", articlemapper.listarticlebytitle (null)); CommentQuery Query = New CommentQuery (); query.setLimit (10); query.setPage (1); query.setarticleid (id); model.addattribute ("ความคิดเห็น", commentservice.listcommentbyarticleid (คำถาม)); กลับ "ส่วนหน้า/บทความ"; } @apioperation (value = "interface articlecomment query") @postmapping ("/comments") @ResponseBody Public DataGridResult ความคิดเห็น (Query Commentquery) {// ตั้งค่าเริ่มต้น 10 query.setLimit (10); ส่งคืนความคิดเห็น Service.listcommentByarticleid (คำถาม); } @apioperation (value = "articlelid") @apiimplicitparam (name = "articleid", value = "articleid", จำเป็น = true, dataType = "long") @postmapping ("/อนุมัติ") -

ในที่สุดก็มีการเรนเดอร์เช่นเดียวกับข้างต้น

เมื่อ pathselectors.none () คือ

เมื่อ pathselectors.any () คือ

เป็นที่ชัดเจนว่าเนื้อหาอินเทอร์เฟซเป็นการเรนเดอร์หรือไม่และมีความรัดกุมและชัดเจนมาก

ในที่สุดดูเหมือนว่าฉันลืมที่จะพูดเส้นทางไปยังเอกสาร Swagger

หากโครงการของคุณอยู่ในไดเรกทอรีราก: http: // localhost: 8080/swagger-ui.html

ถ้าไม่ใช่ไดเรกทอรีรากก็คือ: http: // localhost: 8080/ชื่อโครงการของคุณ/swagger-ui.html

ข้างต้นเป็นเนื้อหาทั้งหมดของบทความนี้ ฉันหวังว่ามันจะเป็นประโยชน์ต่อการเรียนรู้ของทุกคนและฉันหวังว่าทุกคนจะสนับสนุน wulin.com มากขึ้น