簡化 API 更動問題的策略：利用 OpenAPI 文檔與程式碼生成器整合 Client SDK 與伺服器端 End2End 測試

以作者查詢圖書館館藏

、以作者查詢臺灣博碩士

、以作者查詢全國書目

、勘誤回報

、線上人數：127

、訪客IP：3.17.175.239

姓名

高家祥(CHIA-HSIANG KAO) 查詢紙本館藏

畢業系所

資訊工程學系

論文名稱

簡化 API 更動問題的策略：利用 OpenAPI 文檔與程式碼生成器整合 Client SDK 與伺服器端 End2End 測試

相關論文

★ 使用PolyTraceAid進行程式文件覆蓋率計算與分群	★ Support Visual Debugging in Electronic Design Automation Software by xDIVA
★ 設計與實作視覺化追蹤點以支援xDIVA進行程式動畫	★ Combine Internal Test Oracles and Capture/Replay GUI Testing for Precise Replay and Higher Validation Power
★ Dissimilarity of Polymorphic Execution Sequences	★ The Analysis of Capturing System Test Cases into Unit Test Cases
★ 動態延遲載入的測試覆蓋率	★ 建構於JMeter之自動化分散式壓力測試架構
★ 模組化因修改具耦合的程式碼所伴隨的成本漣漪	★ Design a Pluggable Architecture for Layout Algorithms in xDIVA
★ 重複性程式碼檢測之外掛模組設計	★ Visual Perception of Realistic Rendering in xDiva 3D Environment
★ Why and When GUI Test Automation Fails in Practice and Our Solutions to The Problem	★ Why and When GUI Test Automation Fails in Practice and Our Solutions to The Problem
★ Very High Precision Optical Character Recognition For Clean-Fixed-Sized True Type Characters	★ Enhance Korat by Branch Capability in Capture/Replay User Scenario to Industrial Test Case Automation

檔案

[Endnote RIS 格式]

[Bibtex 格式]

[相關文章]

[文章引用]

[完整記錄]

[館藏目錄]

[檢視]

[下載]

本電子論文使用權限為同意立即開放。
已達開放權限電子全文僅授權使用者為學術研究之目的，進行個人非營利性質之檢索、閱讀、列印。
請遵守中華民國著作權法之相關規定，切勿任意重製、散佈、改作、轉貼、播送，以免觸法。

摘要(中)

在一個雲端應用中，伺服器需要讓客戶端可以取得它們所需的資料，而伺服器與客戶端的溝通介面就稱為API（Application Programming Interface）。那為了讓使用API的人易於理解，通常都需要為API撰寫文件，來詳細說明用途。
但是撰寫API文件常會遇到以下問題。首先，文檔內容經常不完整或者是與實際功能不一致。此外，維護文檔通常需要額外的人力，但在小型團隊中很難騰出這樣的人力，這會使得每個人的工作變得緊湊且複雜，進而增加文檔錯誤的發生機率。
另外一方面，在有API後，通常伺服器端會將API封裝成一個模組，稱為SDK（Software Development Kit）。但是通常開發SDK是一件煩人的工作，所以有些團隊會使用程式碼產生器來產生SDK。但是現有的程式碼產生器仍存在許多問題，例如：生成的程式碼過於複雜，不容易根據需求進行客製化。並且，如果要修改程式碼產生器的行為，則需要詳細研究官方文檔和設定。
為了解決上述問題，本論文提出了一種架構。該架構透過分析後端程式碼來建立API文檔，並提高可讀性。同時，我們也開發了一個程式碼產生器，用於生成基本的API介面、測試資料，以提供開發SDK的人員更大的彈性，不受程式碼產生器的限制。

摘要(英)

In a cloud application, servers need to allow clients to access the data they require, and the interface through which servers and clients communicate is called an Application Programming Interface (API). In order to make the API user-friendly and easy to understand, it is usually necessary to write documentation that provides detailed explanations of its usage.

However, there are many challenges when writing API documentation. First, the content of the documentation is frequently incomplete or inconsistent with the actual functionality. Additionally, maintaining the documentation typically requires additional manpower, which can be difficult to allocate in small teams, resulting in increased workload and complexity for each individual and a higher likelihood of documentation errors.

On the other hand, after having an API, the server-side usually packages the API into a module called a Software Development Kit (SDK). However, developing an SDK is often a tedious task, so some teams resort to using code generators to generate the SDK.

But, current code generators, it still have many problems. For example, the generated code can be overly complex and not easily customizable according to specific requirements. Furthermore, making changes to the behavior of a code generator often requires a detailed study of official documentation and configurations.

To address these problems, this paper proposes an architecture that analyzes the backend code to generate API documentation and improve its readability. Additionally, we have developed a code generator that creates basic API interfaces and test data, providing developers who create SDKs with greater flexibility without being constrained by the code generator′s limitations.

關鍵字(中)

★ OpenAPI
★ 程式碼產生器
★ 測試
★ SDK
★ 架構
★ 文檔

關鍵字(英)

★ OpenAPI
★ Code Generator
★ Testing
★ SDK
★ Architecture
★ Documentation

論文目次

一、緒論 1
二、研究背景 6
2-1 HTTP規範 6
2-2 前後端分離 7
2-3 RESTful 8
2-4 OpenAPI 9
2-4-1 Swagger Editor 11
2-4-2 Swagger UI 12
2-5 API開發流程風格 13
2-5-1 Code-First 13
2-5-2 API-First 13
2-6 SDK 14
2-7 Code Generator 15
2-8 裝飾器 17
三、問題描述與分析 20
3-1 後端程式碼與OAS關聯 20
3-1-1 後端的程式碼與OAS各別維護 20
3-1-2 只撰寫OAS並產生後端程式碼 20
3-1-3 利用工具或套件分析程式碼並產生OAS 21
3-2 API與SDK關聯 23
3-2-1 API文檔與SDK分別維護 23
3-2-2 使用OAS產生SDK 23
3-3 後端程式與SDK關聯 27
四、架構整合功能實做 28
4-1 架構規劃 28
4-2 程式碼產生API規範 29
4-2-1 註解 29
4-2-2 裝飾器 31
4-2-3 裝飾器—介面 32
4-2-4 裝飾器—建造者模式 35
4-3 OAS規範產生SDK 40
4-3-1 SDK需求 40
4-3-2 程式碼產生流程 41
4-3-3 產生API函式介面 42
4-3-4 產生API介面 45
4-3-5 產生End2End測試資料 51
五、架構評估 53
5-1 對於架構的評估 53
5-2 維護的方便性 55
5-3 實際的範例 58
六、結論與未來展望 61
七、參考資料 63

參考文獻

[1] Don Box, David Ehnebuske, Gopal Kakivaya, Andrew Layman, Noah Mendelsohn, Henrik Frystyk Nielsen, Satish Thatte, and Dave Winer. 2000. Simple Object Access Protocol (SOAP) 1.1. World Wide Web Consortium note (2000). Retrieved from http://www.w3.org/TR/200.
[2] L. Richardson and S. Ruby, RESTful Web Services, Sebastopol, CA, USA:O′Reilly Media, 2008..
[3] X. Wang, H. Zhao and J. Zhu, "GRPC: A Communication Cooperation Mechanism in Distributed Systems", ACM Operating System Review, vol. 27, no. 3, 1993..
[4] “Michael Meng, Stephanie Steinhardt, and Andreas Schubert. 2019. How developers use API documentation: an observation study. Commun. Des. Q. Rev 7, 2 (July 2019), 40–49. https://doi.org/10.1145/3358931.3358937”.
[5] "OpenAPI," [Online]. Available: https://www.openapis.org/. [Accessed 16 6 2023].
[6] “Wang, S., Tian, Y., & He, D. (2023). Improving API Documentation Comprehensibility via Continuous Optimization and Multilingual SDK. arXiv preprint arXiv:2303.13828.”.
[7] B. (. A. D. I. A. M. A. B. C. h.-1.-4.-1.-6. De, API Documentation.
[8] “A. Neumann, N. Laranjeiro and J. Bernardino, "An analysis of public REST Web service APIs", IEEE Trans. Services Comput., Jun. 2018.”.
[9] "OpenAPI Generator," [Online]. Available: https://openapi-generator.tech/. [Accessed 15 6 2023].
[10] "NSwag," [Online]. Available: https://github.com/RicoSuter/NSwag. [Accessed 12 6 2023].
[11] “L. Murphy, M. B. Kery, O. Alliyu, A. Macvean and B. A. Myers, "Api designers in the field: Design practices and challenges for creating usable apis", 2018 ieee symposium on visual languages and human-centric computing (vl/hcc), pp. 249-258, 2018.”.
[12] "RFC7321," [Online]. Available: https://www.rfc-editor.org/rfc/rfc7231#section-4.3.1. [Accessed 19 6 2023].
[13] "GraphQL," [Online]. Available: https://graphql.org/. [Accessed 13 6 2023].
[14] “R.T. Fielding, Architectural Styles and the Design of Network-Based Software Architectures, 2000.”.
[15] "https://swagger.io/," [Online]. [Accessed 19 6 2023].
[16] "https://raml.org/index.html," [Online]. [Accessed 20 6 2023].
[17] “Mandana Vaziri, Louis Mandel, Avraham Shinnar, Jérôme Siméon, and Martin Hirzel. 2017. Generating chat bots from web API specifications. In Proceedings of the 2017 ACM SIGPLAN International Symposium on New Ideas, New Paradigms, and Reflections on Program”.
[18] S. Editor, "Swagger Editor," [Online]. Available: https://editor.swagger.io/. [Accessed 10 6 2023].
[19] "SwaggerUI," [Online]. Available: https://swagger.io/tools/swagger-ui/.
[20] N. Y. N. U. 9. h. Hyunghun Cho and Sukyoung Ryu. 2014. REST to JavaScript for better client-side development. In Proceedings of the 23rd International Conference on World Wide Web (WWW ′14 Companion). Association for Computing Machinery.
[21] D. R. J. A. C. L. A. (. A. M.-D. M. f. F. B. C. W. S. f. O.-C. M. I. H. S. P. L. S. B. (. M.-D. E. a. S. D. Sferruzza.
[22] "Problems with Swagger," [Online]. Available: https://news.ycombinator.com/item?id=14035936. [Accessed 12 5 2023].
[23] “C. Gao and J. Wei, "Generating Open API Usage Rule from Error Descriptions," 2013 IEEE Seventh International Symposium on Service-Oriented System Engineering, San Francisco, CA, USA, 2013, pp. 245-253, doi: 10.1109/SOSE.2013.32.”.
[24] "Openapi-Generator GitHub Issues," [Online]. Available: https://github.com/OpenAPITools/openapi-generator/issues. [Accessed 22 6 2023].
[25] "NSwag GitHub Issues," [Online]. Available: https://github.com/RicoSuter/NSwag/issues. [Accessed 22 6 2022].
[26] A. Lauret, "6 reasons why generating OpenAPI from code when designing and documenting APIs sucks," 21 5 2021. [Online]. Available: https://apihandyman.io/6-reasons-why-generating-openapi-from-code-when-designing-and-documenting-apis-sucks/. [Accessed 28 5 2023].
[27] F. Z. E. a. C. K. R. ". B. U. F. A. t. U. o. A. 2. 1. W. C. o. R. E. L. I. 2. p. 1.-1. d. 1. M. F. Zibran.
[28] N. Y. N. U. 1. Douglas Kramer. 1999. API documentation from source code comments: a case study of Javadoc. In Proceedings of the 17th annual international conference on Computer documentation (SIGDOC ′99). Association for Computing Machinery.
[29] A. A. a. I. P. ". S. M. S. o. A. D. G. A. 2. 4. E. C. o. S. E. a. A. A. (. P. C. R. 2. p. 4.-4. d. 1. K. Nybom.
[30] ". A. D. F. i. I. S. v. 3. n. 4. p. 6.-7. J.-A. 2. d. 1. G. Uddin and M. P. Robillard.
[31] N. Kamal, API Documentation Generator, 2022.
[32] “C. Gao and J. Wei, "Generating Open API Usage Rule from Error Descriptions," 2013 IEEE Seventh International Symposium on Service-Oriented System Engineering, San Francisco, CA, USA, 2013, pp. 245-253, doi: 10.1109/SOSE.2013.32.”.
[33] "[BUG] Property with oneOf leads to wrong Typescript," [Online]. Available: https://github.com/OpenAPITools/openapi-generator/issues/14806. [Accessed 20 6 2023].
[34] “V. Atlidakis, P. Godefroid and M. Polishchuk, "Restler: Stateful REST API fuzzing", ACM/IEEE International Conference on Software Engineering (ICSE), 2019.”.
[35] “A. Martin-Lopez, S. Segura and A. Ruiz-Cortés, "RESTest: Automated Black-Box Testing of RESTful Web APIs", ACM Int. Symposium on Software Testing and Analysis (ISSTA), pp. 682-685, 2021.”.

指導教授

鄭永斌(Yung-Pin Cheng)

審核日期

2023-8-5

推文