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

簡易檢索 / 詳目顯示

回結果列表

研究生：	高家祥 CHIA-HSIANG KAO
論文名稱：	簡化 API 更動問題的策略：利用 OpenAPI 文檔與程式碼生成器整合 Client SDK 與伺服器端 End2End 測試
指導教授：	鄭永斌 Yung-Pin Cheng
口試委員:
學位類別：	碩士 Master
系所名稱：	資訊電機學院 - 資訊工程學系 Department of Computer Science & Information Engineering
論文出版年：	2023
畢業學年度：	111
語文別：	中文
論文頁數：	78
中文關鍵詞：	OpenAPI 、程式碼產生器、測試、SDK 、架構、文檔
外文關鍵詞：	OpenAPI, Code Generator, Testing, SDK, Architecture, Documentation
相關次數：	點閱：11 下載：0
分享至:	分享至facebook 分享至twitter

查詢本校圖書館目錄查詢臺灣博碩士論文知識加值系統勘誤回報

在一個雲端應用中，伺服器需要讓客戶端可以取得它們所需的資料，而伺服器與客戶端的溝通介面就稱為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.

一、    緒論    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.”.

簡易檢索 / 詳目顯示

相關論文