本發(fā)明屬于軟件開發(fā)領(lǐng)域,具體涉及一種生成本地語言openapi文檔的方法及裝置、實現(xiàn)方法。
背景技術(shù):
1、在軟件開發(fā)領(lǐng)域,api?文檔是開發(fā)者用戶理解和使用軟件系統(tǒng)的重要工具,api文檔需要支持多種語言功能,以便開發(fā)者和用戶能夠在不同的語言環(huán)境中獲取接口文檔的詳細信息。
2、現(xiàn)有的?openapi?和?swagger?工具是廣泛使用的?api?文檔生成工具,它們在api?文檔的自動生成和可視化等方面提供了強大的功能。然而,這些工具的默認實現(xiàn)通常僅支持單一語言的接口文檔。在大多數(shù)情況下,這個單一語言是英語,因為軟件開發(fā)領(lǐng)域中很多文檔和標準都以英語為主要語言。
3、例如,開發(fā)人員使用?swagger?時,通常會在代碼中添加各種?swagger?注解,如@apioperation、@apiimplicitparam等,這些注解的信息在生成的?api?文檔中以開發(fā)人員設(shè)定的單一語言呈現(xiàn),并且沒有簡單的機制將這些信息自動轉(zhuǎn)換為其他語言?,F(xiàn)有的openapi?和?swagger?工具未提供多語言切換和本地化支持,這意味著在?api?文檔的生成過程中,文檔內(nèi)容一旦確定,就很難在不同語言環(huán)境中進行修改或擴展,無法滿足多語言用戶的需求,導致在不同語言環(huán)境中的開發(fā)和使用不夠便捷。
技術(shù)實現(xiàn)思路
1、為解決上述問題,本發(fā)明提供一種生成本地語言openapi文檔的方法及裝置、實現(xiàn)方法,實現(xiàn)openapi文檔中注解信息的本地化語言轉(zhuǎn)換,提高軟件開發(fā)和使用的便捷性。
2、第一方面,本發(fā)明的技術(shù)方案提供一種生成本地語言openapi文檔的方法,該方法基于springfox框架的插件機制實現(xiàn),包括以下步驟:
3、s1,在swagger生成openapi文檔過程中攔截swagger注解,對swagger注解進行解析獲取api接口的相關(guān)信息;
4、s2,調(diào)用spring框架的消息源機制,通過外部配置的語言資源文件獲取所述相關(guān)信息的本地化描述;
5、s3,將所述本地化描述應用到swagger生成openapi文檔中替換所述相關(guān)信息,實現(xiàn)本地語言openapi文檔的生成。
6、在一個可選的實施方式中,步驟s1在swagger生成openapi文檔過程中攔截swagger注解,對swagger注解進行解析獲取api接口的相關(guān)信息,具體包括:
7、s1.1,通過第一上下文對象查找方法獲取api?操作注解,將查找結(jié)果存儲到第一容器對象;
8、s1.2,檢測第一容器對象是否包含非空值,若包含執(zhí)行步驟s1.3,否則不作處理;
9、s1.3,取出第一容器對象中的數(shù)據(jù)值,記為第一數(shù)據(jù)值;
10、s1.4,通過系統(tǒng)輸出打印方法對第一數(shù)據(jù)值進行處理,獲得api接口的操作描述信息和標簽信息;
11、s1.5,通過第二上下文對象查找方法獲取api?隱式參數(shù)集注解,將查找結(jié)果存儲到第二容器對象;
12、s1.6,檢測第二容器對象是否包含非空值,若包含執(zhí)行步驟s1.7,否則不作處理;
13、s1.7,取出第二容器對象中的數(shù)據(jù)值,記為第二數(shù)據(jù)值;
14、s1.8,通過系統(tǒng)輸出打印方法對第二數(shù)據(jù)值進行處理,獲得api接口的參數(shù)集信息;
15、s1.9,通過第三上下文對象查找方法獲取api?隱式參數(shù)注解,將查找結(jié)果存儲到第三容器對象;
16、s1.10,檢測第三容器對象是否包含非空值,若包含執(zhí)行步驟s1.11,否則不作處理;
17、s1.11,取出第三容器對象中的數(shù)據(jù)值,記為第三數(shù)據(jù)值;
18、s1.12,通過系統(tǒng)輸出打印方法對第三數(shù)據(jù)值進行處理,獲得api接口的參數(shù)信息。
19、在一個可選的實施方式中,步驟s2調(diào)用spring框架的消息源機制,通過外部配置的語言資源文件獲取所述相關(guān)信息的本地化描述,具體包括:
20、s2.1,檢測是否獲取到api接口的操作描述信息和標簽信息,若是執(zhí)行步驟s2.2,否則不作處理;
21、s2.2,檢測api接口的標簽信息中是否包含目標標識,若是執(zhí)行步驟s2.3,否則不作處理;
22、s2.3,調(diào)用spring框架的消息源機制,通過外部配置的語言資源文件獲取操作描述信息、參數(shù)集信息、參數(shù)信息的本地化描述。
23、在一個可選的實施方式中,步驟s2.3調(diào)用spring框架的消息源機制,通過外部配置的語言資源文件獲取操作描述信息、參數(shù)集信息、參數(shù)信息的本地化描述,具體包括:
24、s2.31,調(diào)用spring框架的消息源機制,根據(jù)系統(tǒng)默認的語言設(shè)置,獲取區(qū)域設(shè)置參數(shù);
25、s2.32,檢測外部配置的語言資源文件的文件名稱,篩選文件名稱與區(qū)域設(shè)置參數(shù)適配的語言資源文件,即本地化語言資源文件;
26、s2.33,從本地化語言資源文本中查找與操作描述信息、參數(shù)集信息、參數(shù)信息適配的本地化描述,實現(xiàn)操作描述信息、參數(shù)集信息、參數(shù)信息本地化描述的獲取。
27、在一個可選的實施方式中,步驟s2.33從本地化語言資源文本中查找與操作描述信息、參數(shù)集信息、參數(shù)信息適配的本地化描述,具體包括:
28、s2.33.1,根據(jù)接口名稱和操作描述信息,根據(jù)預設(shè)構(gòu)建規(guī)則構(gòu)建操作描述信息鍵;
29、s2.33.2,根據(jù)接口名稱和參數(shù)集名稱,根據(jù)預設(shè)構(gòu)建規(guī)則構(gòu)建參數(shù)集鍵;
30、s2.33.3,根據(jù)接口名稱和參數(shù)名稱,根據(jù)預設(shè)構(gòu)建規(guī)則構(gòu)建參數(shù)鍵;
31、s2.33.4,根據(jù)構(gòu)建操作描述信息鍵、參數(shù)集鍵、參數(shù)鍵從本地化語言資源文本中查找適配的鍵值對;
32、s2.33.5,從查找的鍵值對中獲取與操作描述信息、參數(shù)集信息、參數(shù)信息適配的本地化描述。
33、在一個可選的實施方式中,步驟s3將所述本地化描述應用到swagger生成openapi文檔中替換所述相關(guān)信息,實現(xiàn)本地語言openapi文檔的生成,具體包括:
34、s3.1,通過上下文操作構(gòu)建器將openapi文檔中api接口的操作描述信息更新為對應的本地化描述;
35、s3.2,通過參數(shù)構(gòu)建器將openapi文檔中api接口的參數(shù)集信息中的每個參數(shù)更新為對應的本地化描述;
36、s3.3,通過參數(shù)構(gòu)建器將openapi文檔中api接口的參數(shù)信息更新為對應的本地化描述。
37、第二方面,本發(fā)明的技術(shù)方案提供一種生成本地語言openapi文檔的裝置,包括:
38、api接口信息獲取模塊,用于在swagger生成openapi文檔過程中攔截swagger注解,對swagger注解進行解析獲取api接口的相關(guān)信息;
39、本地化描述獲取模塊,用于調(diào)用spring框架的消息源機制,通過外部配置的語言資源文件獲取所述相關(guān)信息的本地化描述;
40、本地化描述應用模塊,用于將所述本地化描述應用到swagger生成openapi文檔中替換所述相關(guān)信息,實現(xiàn)本地語言openapi文檔的生成。
41、第三方面,本發(fā)明的技術(shù)方案提供一種生成本地語言openapi文檔的實現(xiàn)方法,包括以下步驟:
42、ss1,為每種語言構(gòu)建一個語言資源文件,語言資源文件中存儲api接口的相關(guān)信息及其翻譯描述;
43、ss2,將語言資源文件存儲到本地;
44、ss3,在spring配置中,通過bean注解定義一個消息源機制實例,并指定語言資源文件的存儲位置;
45、ss4,基于springfox框架,通過實現(xiàn)操作構(gòu)建器插件接口,編寫一個自定義插件,并在該插件中重寫應用方法;
46、ss5,在swagger生成openapi文檔過程中調(diào)用所述應用方法實現(xiàn)上述任一項所述的生成本地語言openapi文檔的方法。
47、在一個可選的實施方式中,步驟ss1中語言資源文件中存儲api接口的相關(guān)信息及其翻譯描述,具體包括:
48、將api接口的相關(guān)信息及其翻譯描述以鍵值對形式存儲在語言資源文件中。
49、在一個可選的實施方式中,步驟ss1中為每種語言構(gòu)建一個語言資源文件之后,還包括:
50、為語言資源文件命名,命名名稱中包含語言類型標識。
51、本發(fā)明提供的一種生成本地語言openapi文檔的方法及裝置、實現(xiàn)方法,相對于現(xiàn)有技術(shù),具有以下有益效果:基于springfox框架的插接機制,在swagger生成openapi文檔過程中執(zhí)行插件,攔截swagger注解,并結(jié)合spring框架的消息源機制對swagger注解轉(zhuǎn)換為本地化描述,自動從外部配置的語言資源文件中獲取?api?接口相關(guān)信息的本地化描述,并將這些本地化描述精準地應用到生成的?openapi?文檔中,取代原有的單一語言信息。本發(fā)明克服了現(xiàn)有?openapi?和?swagger?工具僅支持單一語言的局限性,通過利用springfox?框架的插接機制以及?spring?框架的消息源機制,能夠為?api?文檔提供本地化語言支持,使開發(fā)者和用戶可以在本地語言環(huán)境中獲取本地語言的?api?文檔的詳細信息,提升?api?文檔的可用性,提高軟件開發(fā)和使用的便捷性。