รู้เบื้องต้นเกี่ยวกับ Swagger
Swagger เป็นสิ่งที่ดี มันสามารถสร้างเอกสารอินเตอร์เฟส API โดยอัตโนมัติตามรหัสธุรกิจโดยเฉพาะอย่างยิ่งสำหรับโครงการในรูปแบบพักผ่อน นักพัฒนาไม่สามารถรักษา RESTAP API ได้โดยเฉพาะ เฟรมเวิร์กนี้สามารถสร้าง API แบบ RESTFUT โดยอัตโนมัติสำหรับรหัสธุรกิจของคุณและยังมีอินเทอร์เฟซทดสอบที่สอดคล้องกันเพื่อแสดงการตอบสนองโดยอัตโนมัติในรูปแบบ JSON มันอำนวยความสะดวกอย่างมากในการสื่อสารและค่าใช้จ่ายในการประสานงานระหว่างนักพัฒนาแบ็กเอนด์และส่วนหน้า
รู้เบื้องต้นเกี่ยวกับ SpringFox-Swagger
ด้วยฟังก์ชั่นที่ทรงพลังของ Swagger อุตสาหกรรมโอเพนซอร์ส Java Big Spring Framework ได้รับการรักษาอย่างรวดเร็ว มันใช้ประโยชน์อย่างเต็มที่ของตัวเองรวมเข้ากับโครงการของตัวเองและบูรณาการ Spring-Spragger ซึ่งต่อมาพัฒนาเป็น SpringFox SpringFox ใช้เฉพาะลักษณะ AOP ของตัวเองเท่านั้นและรวมเข้ากับปลั๊ก API ธุรกิจรุ่นของตัวเองยังคงพึ่งพา Swagger เพื่อให้บรรลุเป้าหมาย
มีข้อมูลค่อนข้างน้อยเกี่ยวกับกรอบนี้และส่วนใหญ่เป็นการใช้งานง่ายระดับเริ่มต้น ฉันพบข้อผิดพลาดมากมายในกระบวนการรวมกรอบนี้เข้ากับโครงการของฉัน เพื่อที่จะแก้ข้อผิดพลาดเหล่านี้ฉันต้องขุดซอร์สโค้ดเพื่อดูว่ามันคืออะไร บทความนี้อธิบายถึงความเข้าใจของฉันเกี่ยวกับ SpringFox และสิ่งที่ต้องให้ความสนใจในระหว่างการใช้ SpringFox
หลักการทั่วไปของ Springfox
หลักการทั่วไปของ SpringFox คือในกระบวนการเริ่มต้นโครงการในระหว่างกระบวนการเริ่มต้นของบริบทสปริงเฟรมเวิร์กจะโหลดถั่วที่เกี่ยวข้องกับ swagger โดยอัตโนมัติในบริบทปัจจุบันตามการกำหนดค่าและสแกนคลาสที่อาจต้องสร้างเอกสาร API ในระบบโดยอัตโนมัติและสร้างแคชข้อมูลที่สอดคล้องกัน หากเลเยอร์ควบคุม MVC ของโครงการใช้ SpringMVC จะสแกนคลาสคอนโทรลเลอร์ทั้งหมดโดยอัตโนมัติเพื่อสร้างเอกสาร API ที่สอดคล้องกันตามวิธีการในคลาสคอนโทรลเลอร์เหล่านี้
เนื่องจากโครงการของฉันคือ SpringMVC บทความนี้ใช้ SRPING MVC Integration SpringFox เป็นตัวอย่างเพื่อหารือเกี่ยวกับการใช้และหลักการของ SpringFox
ขั้นตอนในการรวม SpringMVC เข้ากับ SpringFox
ขั้นแรกโครงการจำเป็นต้องเพิ่มการพึ่งพาสามประการต่อไปนี้:
<!-การพึ่งพา Sring MVC-> <การพึ่งพา> <roupId> org.springframework </groupId> <ratifactid> Spring-Webmvc </artifactid> <version> 4.2.8.release </SerfINCE> </การพึ่งพาอาศัยกัน> <! <ArtIfactId> SpringFox-Swagger2 </artifactId> <sersion> 2.6.1 </Side> </predency> <!-Swagger-UI ให้การแสดงผล API และการทดสอบอินเทอร์เฟซสำหรับโครงการ-> <การพึ่งพา
การพึ่งพาสามประการข้างต้นเป็นการพึ่งพาพื้นฐานที่สุดสำหรับการรวมโครงการ SpringMVC และ SpringFox และการพึ่งพาอื่น ๆ จะถูกละเว้นที่นี่ อันแรกคือการพึ่งพาพื้นฐานของ SpringMVC ที่สองคือการพึ่งพาอาศัยกันของ Swagger และที่สามคือการพึ่งพาที่เกี่ยวข้องกับอินเตอร์เฟส สิ่งนี้ไม่จำเป็น หากคุณไม่ต้องการใช้อินเทอร์เฟซ API ที่มาพร้อมกับ SpringFox คุณยังไม่สามารถใช้สิ่งนี้และเขียนชุดอินเทอร์เฟซที่เหมาะกับโครงการของคุณ หลังจากเพิ่มการพึ่งพาเหล่านี้ระบบจะเพิ่มแพ็คเกจขวดที่เกี่ยวข้องกับ SpringFox และ Swagger โดยอัตโนมัติ ฉันดูสั้น ๆ และพบว่าส่วนใหญ่มีสิ่งต่อไปนี้:
Springfox-Swagger2-2.6.1.jar
Swagger-Annotations-1.5.10.jar
Swagger-models-1.5.10.jar
SpringFox-Spi-2.6.1.jar
Springfox-core-2.6.1.jar
SpringFox-Schema-2.6.1.jar
Springfox-Swagger-common-2.6.1.jar
Springfox-Spring-Web-2.6.1.jar
guava-17.0.jar
Spring-Plugin-Core-1.2.0.Release.jar
Spring-plug-metadata-1.2.0.release.jar
Spring-Swagger-ui-2.6.1.jar
Jackson-Databind-2.2.3.jar
Jackson-Annotations-2.2.3.jar
ข้างต้นคือขวดที่ฉันคิดว่า Springfox อาจต้องการและอาจไม่แสดงให้เห็นถึงขวดทั้งหมดที่ Springfox ต้องการ จากโถข้างต้นเราจะเห็นได้ว่านอกเหนือจากการพึ่งพา Swagger แล้ว Pringfox ยังต้องใช้ Guava, Spring-Plug, Jackson และการพึ่งพาอื่น ๆ (โปรดทราบว่า Jackson เป็นแพ็คเกจ JAR ที่จำเป็นสำหรับการสร้าง JSON
การใช้ SpringFox อย่างง่าย
หากคุณใช้การกำหนดค่าเริ่มต้นของ SpringFox เท่านั้นการรวมเข้ากับ SpringMVC นั้นง่ายมาก เพียงแค่เขียนคลาสที่คล้ายกับรหัสต่อไปนี้และใส่ไว้ในโครงการของคุณ รหัสมีดังนี้:
@configuration@enablewebmvc@enablewagger2publicclass apiconfig {}โปรดทราบว่าด้านบนเป็นไฟล์คลาส Java ที่ว่างเปล่าชื่อคลาสสามารถระบุได้ตามความประสงค์ แต่คำอธิบายประกอบทั้งสามที่ทำเครื่องหมาย @Configuration, @enableWebMvc และ @enableswagger2 ในคลาสข้างต้นจะต้องเพิ่ม สิ่งนี้ทำให้การรวมพื้นฐานของ SpringMVC และ SpringFox เสร็จสมบูรณ์ ด้วยสามคำอธิบายประกอบหลังจากเริ่มโครงการคุณสามารถใช้ที่อยู่ได้โดยตรงคล้ายกับต่อไปนี้เพื่อดูรายการ API: http://127.0.0.1:8080/jaddemo/swagger-ui.html
นี่เป็นผลที่น่าอัศจรรย์มาก ด้วยคำอธิบายประกอบแบบง่าย ๆ สามข้อระบบจะแสดง API ทั้งหมดของคลาสคอนโทรลเลอร์ทั้งหมดในโครงการโดยอัตโนมัติ ตอนนี้เริ่มต้นด้วยคลาสการกำหนดค่านี้และวิเคราะห์หลักการของมัน ไม่มีรหัสในชั้นเรียนนี้และเห็นได้ชัดว่าคำอธิบายประกอบทั้งสามมีบทบาทสำคัญ ในหมู่พวกเขามีคำอธิบายประกอบ @configuration มีอยู่แล้วในกรอบฤดูใบไม้ผลิ มันเป็นคำอธิบายประกอบที่ระบุโดย @component meta Annotation ดังนั้นด้วยคำอธิบายประกอบนี้สปริงจะยกตัวอย่างชั้นเรียนเป็นถั่วโดยอัตโนมัติและลงทะเบียนในบริบทของฤดูใบไม้ผลิ คำอธิบายประกอบที่สอง @enableWebMvc จึงหมายความว่า SRPingMVC เปิดใช้งาน คลิกคำอธิบายประกอบนี้ใน Eclipse เพื่อดูสั้น ๆ มันคือสิ่งที่ถั่วประเภทมอบหมาย WebMvCconfiguration ลงในบริบทของฤดูใบไม้ผลิผ่านคำอธิบายประกอบ meta @Import (มอบหมาย WebMvCconfiguration.class) ฉันคิดว่าจุดประสงค์ของชั้นเรียนนี้ควรให้การกำหนดค่า SpringMVC บางอย่าง คำอธิบายประกอบที่สาม: @enableswagger2 คุณสามารถนึกถึงชื่อ มันถูกใช้เพื่อรวม swagger 2. ผ่านคำอธิบายประกอบเมตา: @import ({swagger2DocumentationConfiguration.class}) มันแนะนำ swagger2documentationConfiguration ประเภทถั่วและนี่คือการกำหนดค่าหลักของ Swagger รหัสภายในมีดังนี้:
@configuration@import ({springfoxwebmvcconfiguration.class, swaggerCommonConfiguration.class})@ComponentScan (basepackages = {"springfox.documentation.swagger2.readers.parameter" "Springfox.documentation.swagger2.mappers"}) Publicclassswagger2DocumentationConfiguration {@bean สาธารณะ JacksonModuleregistrar Swagger2Module () {returnNewswagger2JacksonModule (); -ส่วนหัวของคลาสนี้ใช้คำอธิบายประกอบบางอย่างจากนั้นแนะนำคลาส SpringFoxWebMvCconfiguration และคลาส SwaggerCommonConfiguration และสแกนถั่วที่เกี่ยวข้องกับ SpringFox .Swagger 2 โดยอัตโนมัติในบริบทของฤดูใบไม้ผลิ ที่นี่สิ่งที่ฉันสนใจมากที่สุดคือคลาส SpringFoxwebMvCconfiguration ฉันเดาว่าชั้นเรียนนี้ควรจะเป็นการกำหนดค่าหลักของ MVC Integrated SpringFox คลิกในและดูรหัสต่อไปนี้:
@configuration@import ({modelsConfiguration.class})@ComponentScan (basepackages = { "Springfox.documentation.spring.web.scanners", "Springfox.documentation.spring.web.readers.operation", "Springfox.documentation.spring.web.readers.operation" "Springfox.documentation.spring.parameter", "Springfox.documentation.spring.web.plugins", "Springfox.documentation.spring.web.paths"})@enablepluginregistries ({{{{{{{{ DocumentationPlugin.class, apilistingBuilderplugin.class, OperationBuilderplugin.class, ParameterBuilderplugin.class, ExpanderameterBuilderplugin.class, ResourceGroupingStrategy.class PathDecorator.class}) PublicClassSpringFoxWebMvCconFiguration {}รหัสต่อไปนี้ในคลาสนี้ไม่มีอะไรมากไปกว่าการเพิ่มถั่วใหม่ผ่านคำอธิบายประกอบ @Bean ฉันไม่สนใจมันมากนัก สิ่งที่ฉันสนใจมากที่สุดคือสิ่งที่เพิ่มเข้าไปในหัวผ่าน @enablepluginregistries SpringFox ขึ้นอยู่กับกลไกการจัดวางสปริงเพื่อรวม Swagger เข้าด้วยกัน Spring-Plug จะใช้งานได้อย่างไร? ฉันยังไม่มีเวลาศึกษาหลักการของการจัดวางฤดูใบไม้ผลิ แต่ด้านล่างนี้ฉันจะพูดถึงว่าฉันเขียนปลั๊กอินปลั๊กอินเพื่อขยายการทำงานของ Swagger ปลั๊กที่เพิ่มด้านบนผ่าน @enablepluginregistries ยังไม่สามารถใช้งานได้ รหัสที่ฉันได้เห็นส่วนใหญ่รวมถึง apilistingBuilderplugin.class, OperationBuilderplugin.class, ParameterBuilderplugin.class, ExpanderameterBuilderplugin.class
apilistingbuilderplugin แรกซึ่งมีสองคลาสการใช้งานคือ apilistingReader และ swaggerapilistingReader ในหมู่พวกเขา apilistingReader จะสร้างรายการ API โดยอัตโนมัติตามประเภทคอนโทรลเลอร์และ SwaggerapilistingReader จะสร้างรายการ API ตามคลาสที่ระบุโดยคำอธิบายประกอบ @API ปลั๊กอิน OperationBuilderPlugin ใช้เพื่อสร้างเอกสาร API เฉพาะ ปลั๊กอินประเภทนี้มีคลาสการใช้งานมากมาย พวกเขาแต่ละคนแบ่งงานของพวกเขาและทำสิ่งต่าง ๆ ของตัวเอง ฉันไม่ได้ดูรายละเอียดอย่างรอบคอบ แต่มุ่งเน้นไปที่หนึ่งในคลาสการใช้งาน: OperationParameterReader คลาสนี้เป็นปลั๊กอินที่ใช้ในการอ่านพารามิเตอร์ API มันขึ้นอยู่กับคลาสเครื่องมือ ModelattributeParameterExpander ซึ่งสามารถแยกวิเคราะห์วัตถุคำสั่งของประเภทที่ไม่ง่ายในพารามิเตอร์วิธีการอินเตอร์เฟสในคอนโทรลเลอร์โดยอัตโนมัติเพื่อให้ได้รายการพารามิเตอร์ที่มีคุณสมบัติทั้งหมด (มีหลุมที่นี่ ปลั๊กอิน ExpanderameterBuilderPlugin ส่วนใหญ่จะใช้เพื่อขยายฟังก์ชั่นบางอย่างของพารามิเตอร์อินเตอร์เฟสเช่นการกำหนดประเภทข้อมูลของพารามิเตอร์นี้และไม่ว่าจะเป็นพารามิเตอร์ที่จำเป็นสำหรับอินเทอร์เฟซนี้หรือไม่ เมื่อระบบเริ่มต้นจะถูกปรับขึ้นบางส่วนจะใช้เพื่อสแกนรายการอินเตอร์เฟสบางรายการจะใช้ในการอ่านพารามิเตอร์อินเตอร์เฟส ฯลฯ วัตถุประสงค์ทั่วไปของพวกเขาคือการสแกนอินเตอร์เฟส API ทั้งหมดในระบบและแคชให้ผู้ใช้ดู ดังนั้นชุดของปลั๊กตารางนี้ปรับแต่งอย่างไรและทางเข้าการดำเนินการของพวกเขาอยู่ที่ไหน?
เราให้ความสนใจกับเนื้อหาของ ComponentsCan Annotation ที่ส่วนหัวรหัสของคลาส SpringFoxWebMVCCONFiguration ด้านบน ในคำอธิบายประกอบนี้แพ็คเกจที่เรียกว่า SpringFox.Documentation.spring.web.plugins ถูกสแกน แพ็คเกจนี้สามารถพบได้ใน SpringFox-Spring-Web-2.6.1.jar ภายใต้แพ็คเกจนี้เราพบว่ามีสองคลาสหลักมากคือ DocumentationPluginsManager และ DocumentationPluginsbootstrapper สำหรับเอกสารแรก PluginsManager เป็นถั่วที่ไม่ได้ใช้อินเทอร์เฟซใด ๆ แต่มีคุณสมบัติมากมายของประเภทปลั๊กอินและทั้งหมดของพวกเขาจะถูกฉีดเข้าไปในค่าคุณสมบัติผ่านคำอธิบายประกอบ @autowired เมื่อรวมชื่อคลาสเข้าด้วยกันมันเป็นเรื่องง่ายที่จะคิดว่านี่เป็นผู้จัดการที่จัดการปลั๊กทั้งหมด เป็นเรื่องง่ายที่จะเข้าใจเนื่องจากการกำหนดค่าของคำอธิบายประกอบส่วนประกอบอินสแตนซ์ปลั๊กทั้งหมดจะถูกสร้างอินสแตนซ์เป็นถั่วภายในฤดูใบไม้ผลิจากนั้นฉีดเข้าไปในเอกสารนี้ PluginsManager อินสแตนซ์และจัดการอย่างสม่ำเสมอ อีกคลาสที่สำคัญในเอกสารประกอบแพ็คเกจนี้ Pluginsbootstrapper คุณสามารถเดาได้โดยดูที่ชื่ออาจเป็นคลาสเริ่มต้นของปลั๊ก เมื่อคุณคลิกและดูข้อมูลเฉพาะคุณจะพบว่ามันเป็นส่วนประกอบที่ระบุโดย @component และวิธีการก่อสร้างของมันจะฉีดอินสแตนซ์ DocumentationPluginsManager ที่เพิ่งอธิบายไว้และสิ่งที่สำคัญที่สุดคือมันยังใช้อินเทอร์เฟซ SmartLifecycle ใครก็ตามที่รู้วัฏจักรชีวิตของถั่วฤดูใบไม้ผลิรู้ว่าเมื่อองค์ประกอบนี้ถูกสร้างอินสแตนซ์เป็นถั่วและได้รับการจัดการในบริบท SRPing วิธีการเริ่มต้น () จะถูกเรียกโดยอัตโนมัติ เมื่อคุณคลิกที่ start () เพื่อดูรหัสคุณจะพบว่ามีบรรทัดของรหัสสแกนโทรม (buildContext (แต่ละ)); ซึ่งใช้ในการสแกนเอกสาร API โดยการติดตามรหัสของวิธีนี้เพิ่มเติมคุณจะพบว่าวิธีนี้จะใช้คุณสมบัติ PlospluginsManager ในที่สุดเพื่อปรับปลั๊กทั้งหมดเข้าด้วยกันเพื่อสแกนระบบทั้งหมดและสร้างเอกสาร API ผลลัพธ์การสแกนจะถูกแคชในคุณสมบัติแผนที่ของคลาสเอกสาร
ข้างต้นเป็นหลักการทั่วไปของ SRPINGMVC การรวม SpringFox ส่วนใหญ่จะฉีดถั่วชุดเข้าไปในบริบท SRPing ผ่านคำอธิบายประกอบ ENABSWAGGRAGE2 และสแกนคลาสคอนโทรลเลอร์ของระบบโดยอัตโนมัติเมื่อระบบเริ่มต้นสร้างข้อมูล API ที่สอดคล้องกันและแคช นอกจากนี้ยังฉีดคลาสคอนโทรลเลอร์บางคลาสที่ระบุโดย @Controller Annotation เป็นรายการสำหรับโมดูล UI เพื่อเข้าถึงรายการ API ตัวอย่างเช่นคลาส Swagger2Controller ในแพ็คเกจ Springfox-Swagger2-2.6.1.jar คอนโทรลเลอร์นี้เป็นที่อยู่อินเตอร์เฟสที่ใช้ในโมดูล UI เพื่อเข้าถึงรายการ API เมื่อคุณเยี่ยมชมที่อยู่ http://127.0.0.1:8080/jaddemo/swagger-ui.html เพื่อดูรายการ API คุณสามารถดูผ่านเบราว์เซอร์ว่ามันได้รับข้อมูล API (รูปแบบ JSON) ผ่านที่อยู่คล้ายกับ http://127.0.0.1:8080/jaddemo/v2/api-docs?group=sysgroup และแสดงบนอินเทอร์เฟซ รายการคอนโทรลเลอร์ที่สอดคล้องกับพื้นหลังของที่อยู่นี้คือคลาส Swagger2Controller ด้านบน หลังจากได้รับคำขอคลาสนี้จะดึงข้อมูล API โดยตรงจากแคชที่เริ่มต้นล่วงหน้าเพื่อสร้างสตริง JSON
หลังจากทำความเข้าใจหลักการของ SpringFox ลองมาดูกันว่าสิ่งที่ฉันพบในระหว่างการใช้ SpringFox
หลุมขนาดใหญ่แรกของ SpringFox: ถั่วที่สร้างขึ้นโดยคลาสการกำหนดค่าจะต้องแชร์บริบทเดียวกับ Spring MVC
ตามที่อธิบายไว้ข้างต้นในโครงการ SpringMVC การรวม SpringFox เป็นเพียงการเขียนคลาสการกำหนดค่าอย่างง่ายดังนี้โดยไม่มีรหัสธุรกิจใด ๆ ในโครงการ
@configuration@enablewebmvc@enablewagger2publicclass apiconfig {}เนื่องจากคำอธิบายประกอบ @Configuration ฤดูใบไม้ผลิจะสร้างอินสแตนซ์เป็นถั่วโดยอัตโนมัติและฉีดเข้าไปในบริบท แต่ข้อผิดพลาดอย่างหนึ่งที่จะสังเกตคือบริบทที่ถั่วนี้ต้องอยู่ในบริบทเดียวกับฤดูใบไม้ผลิ MVC จะเข้าใจได้อย่างไร? เนื่องจากในโครงการ MVC ในฤดูใบไม้ผลิจริงมักจะมีสองบริบทหนึ่งจึงเป็นบริบทที่ตามมาและอีกบริบทคือสปริง MVC (เป็น subcontext ที่ตามบริบท) บริบทคือ org.springframework.web.context.request.requestcontextListener ผู้ฟังที่เกี่ยวข้องกับสปริงในไฟล์ web.xml บริบทที่โหลดมักจะเขียนเป็นไฟล์กำหนดค่าที่เรียกว่า Spring-contet.xml ถั่วที่นี่จะเริ่มต้นในบริบทในที่สุด ส่วนใหญ่รวมถึงบริการ DAO และถั่วอื่น ๆ ในระบบรวมถึงแหล่งข้อมูลสิ่งต่าง ๆ ฯลฯ บริบทอื่นคือ Spring MVC ซึ่งโหลดผ่าน org.springframework.web.servlet.dispatcherservlet ที่เกี่ยวข้องกับ Spring MVC ใน web.xml มันมักจะมีไฟล์กำหนดค่าที่เรียกว่า Spring-MVC.XML เมื่อเขียนคลาส APICONFIG หากเราตัดสินใจที่จะโหลดด้วยคำอธิบายประกอบ @Configuration เราต้องตรวจสอบให้แน่ใจว่าเส้นทางของคลาสนี้อยู่ในขอบเขตพื้นฐานแพคเกจของการกำหนดค่าส่วนประกอบ-สแกนใน SpringMVC เพราะเมื่อ apiconfig ถูกโหลดโดยฤดูใบไม้ผลิชุดถั่วจะถูกฉีด ในถั่วเหล่านี้เพื่อสแกนคลาสคอนโทรลเลอร์ทั้งหมดโดยอัตโนมัติถั่วบางตัวต้องพึ่งพาถั่วบางชนิดใน SpringMVC หากโครงการแยกบริบทของ SRPingMVC ออกจากบริบทเป็น subcontext ของบริบท หากคุณตั้งใจปล่อยให้ถั่วประเภท apiconfig นี้ถูกโหลดด้วยข้อความก่อนหน้านี้เนื่องจากไม่มีคลาสการกำหนดค่าในบริบท MVC ฤดูใบไม้ผลิในบริบทรูท
ในความเป็นจริงฉันไม่เห็นด้วยกับการกำหนดค่า Swagger ผ่านคำอธิบายประกอบ @Configuration เพราะฉันคิดว่าฟังก์ชั่น API ของ Swagger เป็นตัวเลือกสำหรับโครงการการผลิต Swagger ของเรามักจะใช้ในการทดสอบสภาพแวดล้อมสำหรับการพัฒนาทีมส่วนหน้าโครงการหรือสำหรับระบบอื่น ๆ เพื่อรวมอินเทอร์เฟซ เมื่อระบบออนไลน์เป็นไปได้ว่ารายการ API เหล่านี้จะถูกซ่อนไว้ในระบบการผลิต แต่ถ้าการกำหนดค่าถูกเขียนลงในรหัส Java ผ่านการกำหนดคำอธิบายประกอบ @Configuration เมื่อคุณต้องการลบฟังก์ชั่นนี้เมื่อคุณออนไลน์มันจะน่าอายและคุณต้องปรับเปลี่ยนรหัส Java เพื่อคอมไพล์ใหม่ จากนี้ฉันขอแนะนำวิธีการกำหนดค่าไฟล์ XML แบบดั้งเดิมที่สุดในฤดูใบไม้ผลิ วิธีการเฉพาะคือการลบคำอธิบายประกอบ @Configuration และจากนั้นจะเขียนการกำหนดค่าถั่วคล้ายกับ <bean/> ลงในไฟล์การกำหนดค่า Spring XML ในโครงการที่บริบทรูทถูกแยกออกจากบริบท MVC มันจะถูกกำหนดค่าโดยตรงเป็น Spring-MVC.XML ซึ่งทำให้มั่นใจได้ว่าจะต้องอยู่ในบริบทเดียวกับบริบท SpringMVC
หลุมที่ใหญ่ที่สุดเป็นอันดับสองของ SpringFox: พารามิเตอร์ของคลาสคอนโทรลเลอร์ให้ความสนใจเพื่อป้องกันการเกิดซ้ำที่ไม่มีที่สิ้นสุด
Spring MVC มีกลไกการเชื่อมโยงพารามิเตอร์ที่มีประสิทธิภาพซึ่งสามารถผูกพารามิเตอร์การร้องขอโดยอัตโนมัติในวัตถุคำสั่งที่กำหนดเอง ดังนั้นเพื่อที่จะขี้เกียจนักพัฒนาหลายคนใช้วัตถุเอนทิตีโดยตรงเป็นพารามิเตอร์ของวิธีคอนโทรลเลอร์เมื่อเขียนคอนโทรลเลอร์ ตัวอย่างเช่นรหัสตัวอย่างต่อไปนี้:
@RequestMapping (value = "update") การอัปเดตสตริงสาธารณะ (menuvomenuvo, โมเดลโมเดล) {}นี่คือรหัสที่โปรแกรมเมอร์ส่วนใหญ่ชอบเขียนในคอนโทรลเลอร์เพื่อแก้ไขเอนทิตี เมื่อรวมเข้ากับ Swagger มีหลุมขนาดใหญ่ที่นี่ หากคุณสมบัติทั้งหมดใน menuvo เป็นประเภทพื้นฐานก็ไม่เป็นไรไม่มีอะไรผิดปกติ แต่ถ้ามีแอตทริบิวต์ประเภทที่กำหนดเองอื่น ๆ ในคลาสนี้และแอตทริบิวต์นี้โดยตรงหรือโดยอ้อมมีคุณสมบัติของประเภทของตัวเองจะมีปัญหา ตัวอย่างเช่น: หากคลาส Menuvo เป็นคลาสเมนูมันยังมีคุณสมบัติหลักของเมนูเมนูที่แสดงถึงเมนูหลัก ด้วยวิธีนี้โมดูล Swagger จะรายงานข้อผิดพลาดโดยตรงเมื่อระบบเริ่มต้นเนื่องจากไม่สามารถโหลด API ได้ เหตุผลสำหรับข้อผิดพลาดคือเมื่อโหลดวิธีนี้พารามิเตอร์ของวิธีการอัปเดตจะถูกแยกวิเคราะห์ เมื่อพารามิเตอร์ menuvo ไม่ใช่ประเภทง่าย ๆ แอตทริบิวต์คลาสทั้งหมดจะถูกตีความโดยอัตโนมัติซ้ำ สิ่งนี้ทำให้ง่ายต่อการตกอยู่ในการวนซ้ำที่ไม่มีที่สิ้นสุด
เพื่อแก้ปัญหานี้ฉันเพิ่งเขียนคลาสการใช้งานปลั๊กอิน OperationParameterReader และคลาสเครื่องมือ ModelattributeParameterExpander ที่ขึ้นอยู่กับ มันแทนที่สองคลาสดั้งเดิมของ SRPINGFOX ผ่านการกำหนดค่าแทนที่ตรรกะของการแยกวิเคราะห์การวิเคราะห์พารามิเตอร์เช่นคอลัมน์และหลีกเลี่ยงการเรียกซ้ำที่ไม่มีที่สิ้นสุด แน่นอนว่าสิ่งนี้เทียบเท่ากับวิธีการปรับเปลี่ยนระดับซอร์สโค้ด ฉันยังไม่พบวิธีแก้ปัญหาที่สมบูรณ์แบบสำหรับปัญหานี้ดังนั้นฉันสามารถแนะนำให้คุณพยายามหลีกเลี่ยงการเกิดซ้ำที่ไม่มีที่สิ้นสุดนี้เมื่อใช้ Spring-Fox Swagger ท้ายที่สุดสิ่งนี้ไม่เป็นไปตามข้อกำหนดของวัตถุคำสั่ง SpringMVC วัตถุคำสั่งที่มีพารามิเตอร์ SpringMVC นั้นดีกว่าแอตทริบิวต์ประเภทพื้นฐานง่าย ๆ เท่านั้น
หลุมสำคัญที่สามของ SpringFox: การจัดกลุ่ม API ที่เกี่ยวข้อง
SpringFox จะแบ่ง API ทั้งหมดออกเป็นกลุ่มโดยค่าเริ่มต้น เมื่อเข้าถึงผ่านที่อยู่คล้ายกับ http://127.0.0.1:8080/jaddemo/swagger-ui.html รายการ API ทั้งหมดจะโหลดในหน้าเดียวกัน ด้วยวิธีนี้หากระบบมีขนาดใหญ่ขึ้นเล็กน้อยและ API อีกเล็กน้อยหน้าจะถูกแกล้งตายจนตายดังนั้นจึงจำเป็นอย่างยิ่งที่จะต้องจัดกลุ่ม API การจัดกลุ่ม API ถูกกำหนดโดยคำอธิบายประกอบ @bean ในไฟล์การกำหนดค่า APICONF การกำหนดค่าทั่วไปบนอินเทอร์เน็ตมีดังนี้:
@enablewebmvc@enablewagger2publicclass apiconfig {@bean public Docket CustomDocket () {return newDocket (DocumentationType.swagger_2) .apiinfo (apiinfo ()); -ในรหัสข้างต้นใบปะหน้าถูกฉีดผ่าน @Bean การกำหนดค่านี้ไม่จำเป็น หากการกำหนดค่านี้ไม่พร้อมใช้งานเฟรมเวิร์กจะสร้างอินสแตนซ์ใบปะหน้าเริ่มต้นด้วยตัวเอง วัตถุประสงค์ของอินสแตนซ์ใบปะหน้านี้คือการระบุข้อมูลสาธารณะของ API ทั้งหมดที่สามารถจัดการได้เช่นข้อมูลพื้นฐานเช่นเวอร์ชัน API ผู้แต่ง ฯลฯ และเพื่อระบุว่า API ใดแสดงรายการเท่านั้น (กรองโดยที่อยู่ API หรือคำอธิบายประกอบ)
อาจมีหลายกรณีใบปะหน้าเช่นรหัสต่อไปนี้:
@enablewebmvc@enablewagger2publicclass apiconfig {@bean public Docket CustomDocket1 () {return newDocket (DocumentationType.swagger_2) .groupname ("Apigroup1"). apiinfo (apiinfo () } @Bean Public Docket CustomDocket2 () {return newDocket (DocumentationType.swagger_2) .groupname ("Apigroup2"). apiinfo (apiinfo ()). select (). paths (pathselectors.ant ("/ร้าน/**")); -เมื่อมีการกำหนดค่าอินสแตนซ์ใบปะหลายครั้งในโครงการ API สามารถจัดกลุ่มตัวอย่างเช่นรหัสด้านบนจะแบ่ง API ออกเป็นสองกลุ่ม ในกรณีนี้แต่ละกลุ่มจะต้องกำหนดชื่อที่แตกต่างกันเช่น "Apigroup1" และ "Apigroup2" ในรหัสข้างต้น แต่ละกลุ่มสามารถใช้เส้นทางเพื่อระบุกลุ่มที่จะจัดการ API ใดผ่านการแสดงออกที่อยู่สไตล์มด ตัวอย่างเช่นในการกำหนดค่าข้างต้นกลุ่มการจัดการกลุ่มแรกคือ APIs โดยเริ่มต้นของ /sys / APIs การจัดการกลุ่มที่สองกับจุดเริ่มต้นของ /ร้านค้า / แน่นอนว่ามีวิธีการกรองอื่น ๆ อีกมากมายเช่นคำอธิบายประกอบชั้นเรียนคำอธิบายประกอบวิธีการที่อยู่นิพจน์ปกติ ฯลฯ หลังจากการจัดกลุ่มคุณสามารถเลือกกลุ่ม API ที่แตกต่างกันในตัวเลือกดรอปดาวน์ที่มุมขวาบนของอินเทอร์เฟซรายการ API สิ่งนี้จะกระจายรายการ API ของโครงการไปยังหน้าต่างๆ สิ่งนี้จะอำนวยความสะดวกในการจัดการโดยไม่แกล้งทำเป็นตายเพราะหน้าต้องโหลด API มากเกินไป
อย่างไรก็ตามเช่นการใช้ @configuration ฉันไม่เห็นด้วยกับการใช้ @bean เพื่อกำหนดค่าอินสแตนซ์ใบปะหน้าไปยังกลุ่ม API ด้วยเหตุนี้รหัสจะถูกเขียนถึงความตาย ดังนั้นฉันขอแนะนำให้กำหนดค่าอินสแตนซ์ใบปะหน้าของคุณเองในไฟล์ XML เพื่อใช้ฟังก์ชั่นที่คล้ายกันเหล่านี้ แน่นอนเมื่อพิจารณาถึงคุณลักษณะหลายอย่างในใบปะหน้ามันเป็นเรื่องยากมากที่จะกำหนดค่าถั่วโดยตรง คุณสามารถเขียน FactoryBean สำหรับใบปะหน้าด้วยตัวเองแล้วกำหนดค่า FactoryBean ในไฟล์ XML อย่างไรก็ตามเมื่อกำหนดค่าใบปะหน้าเป็น XML คุณจะได้พบกับหลุมขนาดใหญ่อีกอันนั่นคือวิธีการโหลดของสปริงบนถั่วนั้นขี้เกียจโหลดตามค่าเริ่มต้น หลังจากกำหนดค่าถั่วอินสแตนซ์ใบปะหน้าเหล่านี้โดยตรงใน XML คุณจะพบว่าไม่มีผลกระทบและไม่มีรายการการจัดกลุ่มในรายการดรอปดาวน์ที่มุมซ้ายบนของหน้า
ปัญหานี้ทำให้ฉันลำบากเป็นเวลาหลายชั่วโมง ต่อมาจากประสบการณ์มันถูกคาดการณ์ว่าอาจเป็นเพราะถั่วสปริงกำลังโหลดขี้เกียจตามค่าเริ่มต้นและอินสแตนซ์ใบปะหน้านี้ไม่ได้ถูกโหลดลงในบริบทของฤดูใบไม้ผลิ เมื่อปรากฎการเดาของฉันถูกต้อง ฉันไม่รู้ว่านี่เป็นข้อผิดพลาดใน SpringFox หรือไม่หรือถ้าฉันไม่ควรย้ายการกำหนดค่าใบปะหน้าจากรหัส Java ดั้งเดิมไปยังไฟล์การกำหนดค่า XML
ข้อผิดพลาดอื่น ๆ ใน SpringFox: มีข้อผิดพลาดอื่น ๆ ใน SpringFox ตัวอย่างเช่นใน @apioperation Annotation หากแอตทริบิวต์ HTTPMETHOD ไม่ได้ระบุว่าเป็นวิธีการรับหรือโพสต์บางวิธีวิธีทั้งหมดเช่น GET, โพสต์, ลบ, ใส่จะถูกระบุไว้ในรายการ API เพื่อให้รายการ API ซ้ำเกินไปซึ่งน่าเกลียดมาก นอกจากนี้ในระหว่างการทดสอบฉันพบปัญหาการอนุญาตให้เข้าสู่ระบบ ฯลฯ กองเล็ก ๆ เหล่านี้ที่สามารถแก้ไขได้ง่ายขึ้นเนื่องจากพื้นที่ จำกัด ฉันจะไม่พูดอะไรมากมาย นอกจากนี้ยังมีการใช้คำอธิบายประกอบเช่น @api, @apioperation และ @apiparam ฉันจะไม่ทำซ้ำเอกสารมากมายทางออนไลน์นี้
ข้างต้นเป็นเนื้อหาทั้งหมดของบทความนี้ ฉันหวังว่ามันจะเป็นประโยชน์ต่อการเรียนรู้ของทุกคนและฉันหวังว่าทุกคนจะสนับสนุน wulin.com มากขึ้น