API Documentation-Related Problems: A Systematic Mapping Study
Resumo
The growing reliance on Application Programming Interfaces (APIs) in modern systems architecture makes the quality of their documentation critical for abstracting complexity and ensuring effective consumption by developers. However, API documentation frequently suffers from issues arising from maintenance and prioritization failures, leading to operational difficulties, integration errors, and systemic malfunctions. This work presents a Systematic Mapping Study (SMS) focused on identifying and categorizing problems, impacts, and mitigation strategies related to API documentation. The primary study search stage retrieved 314 studies from the Scopus database, which, after filtering and snowballing, resulted in the selection of 61 studies. The mapping revealed 26 distinct problems organized into four categories: “Content”, “Presentation”, “Usability”, and “Sustainability”. From the identified problems, 20 correlated impacts were characterized, exposing a cascading causal relationship where certain impacts manifest as new problems. In light of the magnitude of these challenges, the literature demonstrates a limitation in mitigation strategies, covering only 8 types of actions, which often lack specificity. The results highlight a gap in practical solutions and provide a consolidated foundation to guide future research and the development of more effective tools for the API ecosystem.
Palavras-chave:
API, Systematic Mapping Study, Documentation, Problems, Impacts, Actions
Referências
Emad Aghajani, Csaba Nagy, Olga Lucero Vega-Márquez, Mario Linares-Vásquez, Laura Moreno, Gabriele Bavota, and Michele Lanza. 2019. Software Documentation Issues Unveiled. In 2019 IEEE/ACM 41st International Conference on Software Engineering (ICSE). 1199–1210. DOI: 10.1109/ICSE.2019.00122
George Ajam, Carlos Rodriguez, and Boualem Benatallah. 2021. Scout-bot: Leveraging API Community Knowledge for Exploration and Discovery of API Learning Resources. CLEI Electronic Journal 24 (07 2021). DOI: 10.19153/cleiej.24.2.5
George Ajam, Carlos Rodríguez, and Boualem Benatallah. 2020. API Topics Issues in Stack Overflow QAs Posts: An Empirical Study. In 2020 XLVI Latin American Computing Conference (CLEI). 147–155. DOI: 10.1109/CLEI52000.2020.00024
Seham Alharbi, Dimitris Kolovos, and Nicholas Matragkas. 2022. Synthesising Linear API Usage Examples for API Documentation. In 2022 IEEE International Conference on Software Maintenance and Evolution (ICSME). 607–611. DOI: 10.1109/ICSME55016.2022.00084
Leonardo Araujo, Guillermo Rodríguez, Santiago Vidal, Claudia Marcos, and Rodrigo dos Santos. 2022. Empirical Analysis on OpenAPI Topic Exploration and Discovery to Support the Developer Community. Computing and Informatics 40 (02 2022), 1345–1369. DOI: 10.31577/cai_2021_6_1345
Mehdi Bahrami and Wei-Peng Chen. 2019. WATAPI: Composing Web API Specification from API Documentations through an Intelligent and Interactive Annotation Tool. In 2019 IEEE International Conference on Big Data (Big Data). 4573–4578. DOI: 10.1109/BigData47090.2019.9006355
Mehdi Bahrami and Wei-Peng Chen. 2020. Automated Web Service Specification Generation Through a Transformation-Based Learning. In Services Computing – SCC 2020, Qingyang Wang, Yunni Xia, Sangeetha Seshadri, and Liang-Jie Zhang (Eds.). Springer International Publishing, Cham, 103–119.
Gloria Bondel, Arif Cerit, and Florian Matthes. 2022. Challenges of API Documentation from a Provider Perspective and Best Practices for Examples in Public Web API Documentation. In Proceedings of the 24th International Conference on Enterprise Information Systems - Volume 2: ICEIS. INSTICC, SciTePress, 268–279. DOI: 10.5220/0011089700003179
Liang Cai, Haoye Wang, Qiao Huang, Xin Xia, Zhenchang Xing, and David Lo. 2019. BIKER: a tool for Bi-information source based API method recommendation. In Proceedings of the 2019 27th ACM Joint Meeting on European Software Engineering Conference and Symposium on the Foundations of Software Engineering (Tallinn, Estonia) (ESEC/FSE 2019). Association for Computing Machinery, New York, NY, USA, 1075–1079. DOI: 10.1145/3338906.3341174
Hanyang Cao, Jean-Rémy Falleri, and Xavier Blanc. 2017. Automated Generation of REST API Specification from Plain HTML Documentation. In Service-Oriented Computing: 15th International Conference, ICSOC 2017, Malaga, Spain, November 13–16, 2017, Proceedings (Malaga, Spain). Springer-Verlag, Berlin, Heidelberg, 453–461. DOI: 10.1007/978-3-319-69035-3_32
Luca Chiodini, Simone Piatti, and Matthias Hauswirth. 2024. Judicious: API Documentation for Novices. In Proceedings of the 2024 ACM SIGPLAN International Symposium on SPLASH-E (Pasadena, CA, USA) (SPLASH-E ’24). Association for Computing Machinery, New York, NY, USA, 89–97. DOI: 10.1145/3689493.3689987
Michael Coblenz, William Guo, Kevin Voozhian, and Jeffrey S. Foster. 2023. A Qualitative Study of REST API Design and Specification Practices. In 2023 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC). 148–156. DOI: 10.1109/VL-HCC57772.2023.00025
Daniela S Cruzes and Tore Dyba. 2011. Recommended steps for thematic synthesis in software engineering. In 2011 international symposium on empirical software engineering and measurement. IEEE, 275–284.
Alex Cummaudo, Rajesh Vasa, John Grundy, and Mohamed Abdelrazek. 2022. Requirements of API Documentation: A Case Study into Computer Vision Services. IEEE Transactions on Software Engineering 48, 6 (2022), 2010–2027. DOI: 10.1109/TSE.2020.3047088
Fernanda Madeiral Delfim, Klérisson V. R. Paixão, Damien Cassou, and Marcelo de Almeida Maia. 2016. Redocumenting APIs with crowd knowledge: a coverage analysis based on question types. Journal of the Brazilian Computer Society 22, 1 (2016), 9. DOI: 10.1186/s13173-016-0049-0
Hamza Ed-douibi, Javier Luis Cánovas Izquierdo, and Jordi Cabot. 2017. Example-Driven Web API Specification Discovery. In Modelling Foundations and Applications, Anthony Anjorin and Huáscar Espinoza (Eds.). Springer International Publishing, Cham, 267–284.
Akalanka Galappaththi, Sarah Nadi, and Christoph Treude. 2024. An Empirical Study of API Misuses of Data-Centric Libraries. In Proceedings of the 18th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement (Barcelona, Spain) (ESEM ’24). Association for Computing Machinery, New York, NY, USA, 245–256. DOI: 10.1145/3674805.3686685
Andrew Head, Caitlin Sadowski, Emerson Murphy-Hill, and Andrea Knight. 2018. When not to comment: questions and tradeoffs with API documentation for C++ projects. In Proceedings of the 40th International Conference on Software Engineering (Gothenburg, Sweden) (ICSE ’18). Association for Computing Machinery, New York, NY, USA, 643–653. DOI: 10.1145/3180155.3180176
Amber Horvath, Michael Xieyang Liu, River Hendriksen, Connor Shannon, Emma Paterson, Kazi Jawad, Andrew Macvean, and Brad A Myers. 2022. Understanding How Programmers Can Use Annotations on Documentation (CHI ’22). Association for Computing Machinery, New York, NY, USA, Article 69, 16 pages. DOI: 10.1145/3491102.3502095
Masaki Hosono, Hironori Washizaki, Yoshiaki Fukazawa, and Kiyoshi Honda. 2018. An Empirical Study on the Reliability of the Web API Document. In 2018 25th Asia-Pacific Software Engineering Conference (APSEC). 715–716. DOI: 10.1109/APSEC.2018.00103
Masaki Hosono, Hironori Washizaki, Kiyoshi Honda, Hiromasa Nagumo, Hisanobu Sonoda, Yoshiaki Fukazawa, Kazuki Munakata, Takao Nakagawa, Yusuke Nemoto, Susumu Tokumoto, and Supasit Monpratarnchai. 2019. Inappropriate Usage Examples in Web API Documentations. In 2019 IEEE International Conference on Software Maintenance and Evolution (ICSME). 343–347. DOI: 10.1109/ICSME.2019.00052
Peiwei Hu, Ruigang Liang, Ying Cao, Kai Chen, and Runze Zhang. 2023. AURC: detecting errors in program code and documentation. In Proceedings of the 32nd USENIX Conference on Security Symposium (Anaheim, CA, USA) (SEC ’23). USENIX Association, USA, Article 80, 18 pages.
Ruikai Huang, Manish Motwani, Idel Martinez, and Alessandro Orso. 2024. Generating REST API Specifications through Static Analysis. In Proceedings of the IEEE/ACM 46th International Conference on Software Engineering (Lisbon, Portugal) (ICSE ’24). Association for Computing Machinery, New York, NY, USA, Article 107, 13 pages. DOI: 10.1145/3597503.3639137
Siyuan Jiang, Ameer Armaly, Collin McMillan, Qiyu Zhi, and Ronald Metoyer. 2018. Documenting API Input/Output Examples. arXiv:1703.09613 [cs.SE] [link]
Junaed Younus Khan, Md. Tawkat Islam Khondaker, Gias Uddin, and Anindya Iqbal. 2021. Automatic Detection of Five API Documentation Smells: Practitioners’ Perspectives. In 2021 IEEE International Conference on Software Analysis, Evolution and Reengineering (SANER). 318–329. DOI: 10.1109/SANER50967.2021.00037
István Koren and Ralf Klamma. 2018. The Exploitation of OpenAPI Documentation for the Generation of Web Frontends. In Companion Proceedings of the The Web Conference 2018 (Lyon, France) (WWW ’18). International World Wide Web Conferences Steering Committee, Republic and Canton of Geneva, CHE, 781–787. DOI: 10.1145/3184558.3188740
Rediana Koçi, Xavier Franch, Petar Jovanovic, and Alberto Abelló. 2019. Classification of Changes in API Evolution. In 2019 IEEE 23rd International Enterprise Distributed Object Computing Conference (EDOC). 243–249. DOI: 10.1109/EDOC.2019.00037
Arina Kudriavtseva, Nisar Ahmad Hotak, and Olga Gadyatskaya. 2025. My Code Is Less Secure with Gen AI: Surveying Developers’ Perceptions of the Impact of Code Generation Tools on Security. In Proceedings of the 40th ACM/SIGAPP Symposium on Applied Computing (Catania International Airport, Catania, Italy) (SAC ’25). Association for Computing Machinery, New York, NY, USA, 1637–1646. DOI: 10.1145/3672608.3707778
Raquel Lafeta, Thiago Lafeta, and Marcelo Maia. 2020. An Automated Approach for Constructing Framework Instantiation Documentation. International Journal of Software Engineering and Knowledge Engineering 30 (04 2020), 575–601. DOI: 10.1142/S0218194020500205
Maxime Lamothe. 2020. Bridging the Divide Between API Users and API Developers by Mining Public Code Repositories. In 2020 IEEE/ACM 42nd International Conference on Software Engineering: Companion Proceedings (ICSE-Companion). 178–181.
Seonah Lee, Rongxin Wu, Shing-Chi Cheung, and Sungwon Kang. 2021. Automatic Detection and Update Suggestion for Outdated API Names in Documentation. IEEE Transactions on Software Engineering 47, 4 (2021), 653–675. DOI: 10.1109/TSE.2019.2901459
Hongwei Li, Sirui Li, Jiamou Sun, Zhenchang Xing, Xin Peng, Mingwei Liu, and Xuejiao Zhao. 2018. Improving API Caveats Accessibility by Mining API Caveats Knowledge Graph. In 2018 IEEE International Conference on Software Maintenance and Evolution (ICSME). 183–193. DOI: 10.1109/ICSME.2018.00028
Li Li, Jun Gao, Tegawendé F. Bissyandé, Lei Ma, Xin Xia, and Jacques Klein. 2018. Characterising deprecated Android APIs (MSR ’18). Association for Computing Machinery, New York, NY, USA, 254–264. DOI: 10.1145/3196398.3196419
Ruishi Li, Yunfei Yang, Jinghua Liu, Peiwei Hu, and Guozhu Meng. 2022. The inconsistency of documentation: a study of online C standard library documents. Cybersecurity 5 (07 2022), 14. DOI: 10.1186/s42400-022-00118-9
Meherun Nesa Lucky, Marco Cremaschi, Barbara Lodigiani, Antonio Menolascina, and Flavio De Paoli. 2016. Enriching API Descriptions by Adding API Profiles Through Semantic Annotation. In Service-Oriented Computing, Quan Z. Sheng, Eleni Stroulia, Samir Tata, and Sami Bhiri (Eds.). Springer International Publishing, Cham, 780–794.
Michael Meng, Stephanie Steinhardt, and Andreas Schubert. 2018. Application Programming Interface Documentation: What Do Software Developers Want? Journal of Technical Writing and Communication 48 (07 2018), 295–330. DOI: 10.1177/0047281617721853
Michael Meng, Stephanie M. Steinhardt, and Andreas Schubert. 2020. Optimizing API Documentation: Some Guidelines and Effects. In Proceedings of the 38th ACM International Conference on Design of Communication (Denton, TX, USA) (SIGDOC ’20). Association for Computing Machinery, New York, NY, USA, Article 24, 11 pages. DOI: 10.1145/3380851.3416759
Michał Michalski, Piotr Kosko, Dawid Juszczak, and Hobum Kwon. 2020. EWIDL: Single-Source Web API Documentation Management System. In 2020 IEEE International Conference on Software Maintenance and Evolution (ICSME). 723–726. DOI: 10.1109/ICSME46990.2020.00081
Mathieu Nassif, Zara Horlacher, and Martin P. Robillard. 2022. Casdoc: Unobtrusive Explanations in Code Examples. In 2022 IEEE/ACM 30th International Conference on Program Comprehension (ICPC). 631–635. DOI: 10.1145/3524610.3527730
Andy Neumann, Nuno Laranjeiro, and Jorge Bernardino. 2021. An Analysis of Public REST Web Service APIs. IEEE Transactions on Services Computing 14, 4 (2021), 957–970. DOI: 10.1109/TSC.2018.2847344
Kristian Nybom, Adnan Ashraf, and Ivan Porres. 2018. A Systematic Mapping Study on API Documentation Generation Approaches. In 2018 44th Euromicro Conference on Software Engineering and Advanced Applications (SEAA). 462–469. DOI: 10.1109/SEAA.2018.00081
Rahul Pandita, Kunal Taneja, Laurie Williams, and Teresa Tung. 2016. ICON: Inferring Temporal Constraints from Natural Language API Descriptions. In 2016 IEEE International Conference on Software Maintenance and Evolution (ICSME). 378–388. DOI: 10.1109/ICSME.2016.59
Xin Peng, Yifan Zhao, Mingwei Liu, Fengyi Zhang, Yang Liu, Xin Wang, and Zhenchang Xing. 2018. Automatic Generation of API Documentations for Open-Source Projects. In 2018 IEEE Third International Workshop on Dynamic Software Documentation (DySDoc3). 7–8. DOI: 10.1109/DySDoc3.2018.00010
Kai Petersen, Robert Feldt, Shahid Mujtaba, and Michael Mattsson. 2008. Systematic mapping studies in software engineering. In 12th international conference on evaluation and assessment in software engineering (EASE). BCS Learning & Development.
Hung Phan, Hoan Anh Nguyen, Tien N. Nguyen, and Hridesh Rajan. 2017. Statistical Learning for Inference between Implementations and Documentation. In 2017 IEEE/ACM 39th International Conference on Software Engineering: New Ideas and Emerging Technologies Results Track (ICSE-NIER). 27–30. DOI: 10.1109/ICSE-NIER.2017.9
Martin P. Robillard, Andrian Marcus, Christoph Treude, Gabriele Bavota, Oscar Chaparro, Neil Ernst, Marco Aurélio Gerosa, Michael Godfrey, Michele Lanza, Mario Linares-Vásquez, Gail C. Murphy, Laura Moreno, David Shepherd, and Edmund Wong. 2017. On-demand Developer Documentation. In 2017 IEEE International Conference on Software Maintenance and Evolution (ICSME). 479–483. DOI: 10.1109/ICSME.2017.17
Anand Ashok Sawant, Guangzhe Huang, Gabriel Vilen, Stefan Stojkovski, and Alberto Bacchelli. 2018. Why are Features Deprecated? An Investigation Into the Motivation Behind Deprecation. In 2018 IEEE International Conference on Software Maintenance and Evolution (ICSME). 13–24. DOI: 10.1109/ICSME.2018.00011
S. M. Sohan, Craig Anslow, and Frank Maurer. 2017. Automated example oriented REST API documentation at Cisco. In 2017 IEEE/ACM 39th International Conference on Software Engineering: Software Engineering in Practice Track (ICSE-SEIP). 213–222. DOI: 10.1109/ICSE-SEIP.2017.11
S M Sohan, Frank Maurer, Craig Anslow, and Martin P. Robillard. 2017. A study of the effectiveness of usage examples in REST API documentation. In 2017 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC). 53–61. DOI: 10.1109/VLHCC.2017.8103450
Donna Spencer. 2009. Card sorting: Designing usable categories. Rosenfeld Media.
Peng Sun, Chris Brown, Ivan Beschastnikh, and Kathryn T. Stolee. 2019. Mining Specifications from Documentation using a Crowd. In 2019 IEEE 26th International Conference on Software Analysis, Evolution and Reengineering (SANER). 275–286. DOI: 10.1109/SANER.2019.8668025
Yida Tao, Jiefang Jiang, Yepang Liu, Zhiwu Xu, and Shengchao Qin. 2021. Understanding performance concerns in the API documentation of data science libraries. In Proceedings of the 35th IEEE/ACM International Conference on Automated Software Engineering (Virtual Event, Australia) (ASE ’20). Association for Computing Machinery, New York, NY, USA, 895–906. DOI: 10.1145/3324884.3416543
Yuan Tian, Ferdian Thung, Abhishek Sharma, and David Lo. 2017. APIBot: Question answering bot for API documentation. In 2017 32nd IEEE/ACM International Conference on Automated Software Engineering (ASE). 153–158. DOI: 10.1109/ASE.2017.8115628
Gias Uddin, Foutse Khomh, and Chanchal K Roy. 2019. Towards Crowd-Sourced API Documentation. In 2019 IEEE/ACM 41st International Conference on Software Engineering: Companion Proceedings (ICSE-Companion). 310–311. DOI: 10.1109/ICSECompanion.2019.00129
Gias Uddin and Martin P. Robillard. 2015. How API Documentation Fails. IEEE Software 32, 4 (July 2015), 68–75. DOI: 10.1109/MS.2014.80. Acesso em: 28 maio 2025.
Daria Usova. 2023. Generating a Formalized REST API Definition Language for a Dynamic Framework Without Annotations Using Static Analysis Tools. In Proceedings of the 2023 IEEE International Conference on Engineering, Technology and Innovation (ICE/ITMC). 1710–1714. DOI: 10.1109/EDM58354.2023.10225100. Acesso em: 28 maio 2025.
Shujun Wang, Yongqiang Tian, and Dengcheng He. 2023. gDoc: Automatic Generation of Structured API Documentation. In Companion Proceedings of the ACM Web Conference 2023 (Austin, TX, USA) (WWW ’23 Companion). Association for Computing Machinery, New York, NY, USA, 53–56. DOI: 10.1145/3543873.3587310
Rahulkrishna Yandrapally, Saurabh Sinha, Rachel Tzoref-Brill, and Ali Mesbah. 2023. Carving UI Tests to Generate API Tests and API Specification. arXiv:2305.14692 [cs.SE] [link]
Jinqiu Yang, Erik Wittern, Annie T. T. Ying, Julian Dolby, and Lin Tan. 2018. Automatically Extracting Web API Specifications from HTML Documentation. arXiv:1801.08928 [cs.SE] [link]
Jinqiu Yang, Erik Wittern, Annie T. T. Ying, Julian Dolby, and Lin Tan. 2018. Towards extracting web API specifications from documentation. In Proceedings of the 15th International Conference on Mining Software Repositories (Gothenburg, Sweden) (MSR ’18). Association for Computing Machinery, New York, NY, USA, 454–464. DOI: 10.1145/3196398.3196411
Jingxuan Zhang, He Jiang, Zhilei Ren, Tao Zhang, and Zhiqiu Huang. 2021. Enriching API Documentation with Code Samples and Usage Scenarios from Crowd Knowledge. IEEE Transactions on Software Engineering 47, 6 (2021), 1299–1314. DOI: 10.1109/TSE.2019.2919304
Neng Zhang, Jian Wang, Keqing He, Zheng Li, and Yiwang Huang. 2019. Mining and clustering service goals for RESTful service discovery. Knowl. Inf. Syst. 58, 3 (March 2019), 669–700. DOI: 10.1007/s10115-018-1171-4
Neng Zhang, Ying Zou, Xin Xia, Qiao Huang, David Lo, and Shanping Li. 2023. Web APIs: Features, Issues, and Expectations – A Large-Scale Empirical Study of Web APIs From Two Publicly Accessible Registries Using Stack Overflow and a User Survey. IEEE Transactions on Software Engineering 49, 2 (2023), 498–528. DOI: 10.1109/TSE.2022.3154769
Yu Zhou, Ruihang Gu, Taolue Chen, Zhiqiu Huang, Sebastiano Panichella, and Harald Gall. 2017. Analyzing APIs Documentation and Code to Detect Directive Defects. In 2017 IEEE/ACM 39th International Conference on Software Engineering (ICSE). 27– 37. DOI: 10.1109/ICSE.2017.11
Yu Zhou, Changzhi Wang, Xin Yan, Taolue Chen, Sebastiano Panichella, and Harald Gall. 2020. Automatic Detection and Repair Recommendation of Directive Defects in Java API Documentation. IEEE Transactions on Software Engineering 46, 9 (2020), 1004–1023. DOI: 10.1109/TSE.2018.2872971
Adam Štšpánek, David Kuťák, Barbora Kozlíková, and Jan Byška. 2024. Interactive Diagrams for Software Documentation. In 2024 IEEE Working Conference on Software Visualization (VISSOFT). 12–23. DOI: 10.1109/VISSOFT64034.2024.00012
George Ajam, Carlos Rodriguez, and Boualem Benatallah. 2021. Scout-bot: Leveraging API Community Knowledge for Exploration and Discovery of API Learning Resources. CLEI Electronic Journal 24 (07 2021). DOI: 10.19153/cleiej.24.2.5
George Ajam, Carlos Rodríguez, and Boualem Benatallah. 2020. API Topics Issues in Stack Overflow QAs Posts: An Empirical Study. In 2020 XLVI Latin American Computing Conference (CLEI). 147–155. DOI: 10.1109/CLEI52000.2020.00024
Seham Alharbi, Dimitris Kolovos, and Nicholas Matragkas. 2022. Synthesising Linear API Usage Examples for API Documentation. In 2022 IEEE International Conference on Software Maintenance and Evolution (ICSME). 607–611. DOI: 10.1109/ICSME55016.2022.00084
Leonardo Araujo, Guillermo Rodríguez, Santiago Vidal, Claudia Marcos, and Rodrigo dos Santos. 2022. Empirical Analysis on OpenAPI Topic Exploration and Discovery to Support the Developer Community. Computing and Informatics 40 (02 2022), 1345–1369. DOI: 10.31577/cai_2021_6_1345
Mehdi Bahrami and Wei-Peng Chen. 2019. WATAPI: Composing Web API Specification from API Documentations through an Intelligent and Interactive Annotation Tool. In 2019 IEEE International Conference on Big Data (Big Data). 4573–4578. DOI: 10.1109/BigData47090.2019.9006355
Mehdi Bahrami and Wei-Peng Chen. 2020. Automated Web Service Specification Generation Through a Transformation-Based Learning. In Services Computing – SCC 2020, Qingyang Wang, Yunni Xia, Sangeetha Seshadri, and Liang-Jie Zhang (Eds.). Springer International Publishing, Cham, 103–119.
Gloria Bondel, Arif Cerit, and Florian Matthes. 2022. Challenges of API Documentation from a Provider Perspective and Best Practices for Examples in Public Web API Documentation. In Proceedings of the 24th International Conference on Enterprise Information Systems - Volume 2: ICEIS. INSTICC, SciTePress, 268–279. DOI: 10.5220/0011089700003179
Liang Cai, Haoye Wang, Qiao Huang, Xin Xia, Zhenchang Xing, and David Lo. 2019. BIKER: a tool for Bi-information source based API method recommendation. In Proceedings of the 2019 27th ACM Joint Meeting on European Software Engineering Conference and Symposium on the Foundations of Software Engineering (Tallinn, Estonia) (ESEC/FSE 2019). Association for Computing Machinery, New York, NY, USA, 1075–1079. DOI: 10.1145/3338906.3341174
Hanyang Cao, Jean-Rémy Falleri, and Xavier Blanc. 2017. Automated Generation of REST API Specification from Plain HTML Documentation. In Service-Oriented Computing: 15th International Conference, ICSOC 2017, Malaga, Spain, November 13–16, 2017, Proceedings (Malaga, Spain). Springer-Verlag, Berlin, Heidelberg, 453–461. DOI: 10.1007/978-3-319-69035-3_32
Luca Chiodini, Simone Piatti, and Matthias Hauswirth. 2024. Judicious: API Documentation for Novices. In Proceedings of the 2024 ACM SIGPLAN International Symposium on SPLASH-E (Pasadena, CA, USA) (SPLASH-E ’24). Association for Computing Machinery, New York, NY, USA, 89–97. DOI: 10.1145/3689493.3689987
Michael Coblenz, William Guo, Kevin Voozhian, and Jeffrey S. Foster. 2023. A Qualitative Study of REST API Design and Specification Practices. In 2023 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC). 148–156. DOI: 10.1109/VL-HCC57772.2023.00025
Daniela S Cruzes and Tore Dyba. 2011. Recommended steps for thematic synthesis in software engineering. In 2011 international symposium on empirical software engineering and measurement. IEEE, 275–284.
Alex Cummaudo, Rajesh Vasa, John Grundy, and Mohamed Abdelrazek. 2022. Requirements of API Documentation: A Case Study into Computer Vision Services. IEEE Transactions on Software Engineering 48, 6 (2022), 2010–2027. DOI: 10.1109/TSE.2020.3047088
Fernanda Madeiral Delfim, Klérisson V. R. Paixão, Damien Cassou, and Marcelo de Almeida Maia. 2016. Redocumenting APIs with crowd knowledge: a coverage analysis based on question types. Journal of the Brazilian Computer Society 22, 1 (2016), 9. DOI: 10.1186/s13173-016-0049-0
Hamza Ed-douibi, Javier Luis Cánovas Izquierdo, and Jordi Cabot. 2017. Example-Driven Web API Specification Discovery. In Modelling Foundations and Applications, Anthony Anjorin and Huáscar Espinoza (Eds.). Springer International Publishing, Cham, 267–284.
Akalanka Galappaththi, Sarah Nadi, and Christoph Treude. 2024. An Empirical Study of API Misuses of Data-Centric Libraries. In Proceedings of the 18th ACM/IEEE International Symposium on Empirical Software Engineering and Measurement (Barcelona, Spain) (ESEM ’24). Association for Computing Machinery, New York, NY, USA, 245–256. DOI: 10.1145/3674805.3686685
Andrew Head, Caitlin Sadowski, Emerson Murphy-Hill, and Andrea Knight. 2018. When not to comment: questions and tradeoffs with API documentation for C++ projects. In Proceedings of the 40th International Conference on Software Engineering (Gothenburg, Sweden) (ICSE ’18). Association for Computing Machinery, New York, NY, USA, 643–653. DOI: 10.1145/3180155.3180176
Amber Horvath, Michael Xieyang Liu, River Hendriksen, Connor Shannon, Emma Paterson, Kazi Jawad, Andrew Macvean, and Brad A Myers. 2022. Understanding How Programmers Can Use Annotations on Documentation (CHI ’22). Association for Computing Machinery, New York, NY, USA, Article 69, 16 pages. DOI: 10.1145/3491102.3502095
Masaki Hosono, Hironori Washizaki, Yoshiaki Fukazawa, and Kiyoshi Honda. 2018. An Empirical Study on the Reliability of the Web API Document. In 2018 25th Asia-Pacific Software Engineering Conference (APSEC). 715–716. DOI: 10.1109/APSEC.2018.00103
Masaki Hosono, Hironori Washizaki, Kiyoshi Honda, Hiromasa Nagumo, Hisanobu Sonoda, Yoshiaki Fukazawa, Kazuki Munakata, Takao Nakagawa, Yusuke Nemoto, Susumu Tokumoto, and Supasit Monpratarnchai. 2019. Inappropriate Usage Examples in Web API Documentations. In 2019 IEEE International Conference on Software Maintenance and Evolution (ICSME). 343–347. DOI: 10.1109/ICSME.2019.00052
Peiwei Hu, Ruigang Liang, Ying Cao, Kai Chen, and Runze Zhang. 2023. AURC: detecting errors in program code and documentation. In Proceedings of the 32nd USENIX Conference on Security Symposium (Anaheim, CA, USA) (SEC ’23). USENIX Association, USA, Article 80, 18 pages.
Ruikai Huang, Manish Motwani, Idel Martinez, and Alessandro Orso. 2024. Generating REST API Specifications through Static Analysis. In Proceedings of the IEEE/ACM 46th International Conference on Software Engineering (Lisbon, Portugal) (ICSE ’24). Association for Computing Machinery, New York, NY, USA, Article 107, 13 pages. DOI: 10.1145/3597503.3639137
Siyuan Jiang, Ameer Armaly, Collin McMillan, Qiyu Zhi, and Ronald Metoyer. 2018. Documenting API Input/Output Examples. arXiv:1703.09613 [cs.SE] [link]
Junaed Younus Khan, Md. Tawkat Islam Khondaker, Gias Uddin, and Anindya Iqbal. 2021. Automatic Detection of Five API Documentation Smells: Practitioners’ Perspectives. In 2021 IEEE International Conference on Software Analysis, Evolution and Reengineering (SANER). 318–329. DOI: 10.1109/SANER50967.2021.00037
István Koren and Ralf Klamma. 2018. The Exploitation of OpenAPI Documentation for the Generation of Web Frontends. In Companion Proceedings of the The Web Conference 2018 (Lyon, France) (WWW ’18). International World Wide Web Conferences Steering Committee, Republic and Canton of Geneva, CHE, 781–787. DOI: 10.1145/3184558.3188740
Rediana Koçi, Xavier Franch, Petar Jovanovic, and Alberto Abelló. 2019. Classification of Changes in API Evolution. In 2019 IEEE 23rd International Enterprise Distributed Object Computing Conference (EDOC). 243–249. DOI: 10.1109/EDOC.2019.00037
Arina Kudriavtseva, Nisar Ahmad Hotak, and Olga Gadyatskaya. 2025. My Code Is Less Secure with Gen AI: Surveying Developers’ Perceptions of the Impact of Code Generation Tools on Security. In Proceedings of the 40th ACM/SIGAPP Symposium on Applied Computing (Catania International Airport, Catania, Italy) (SAC ’25). Association for Computing Machinery, New York, NY, USA, 1637–1646. DOI: 10.1145/3672608.3707778
Raquel Lafeta, Thiago Lafeta, and Marcelo Maia. 2020. An Automated Approach for Constructing Framework Instantiation Documentation. International Journal of Software Engineering and Knowledge Engineering 30 (04 2020), 575–601. DOI: 10.1142/S0218194020500205
Maxime Lamothe. 2020. Bridging the Divide Between API Users and API Developers by Mining Public Code Repositories. In 2020 IEEE/ACM 42nd International Conference on Software Engineering: Companion Proceedings (ICSE-Companion). 178–181.
Seonah Lee, Rongxin Wu, Shing-Chi Cheung, and Sungwon Kang. 2021. Automatic Detection and Update Suggestion for Outdated API Names in Documentation. IEEE Transactions on Software Engineering 47, 4 (2021), 653–675. DOI: 10.1109/TSE.2019.2901459
Hongwei Li, Sirui Li, Jiamou Sun, Zhenchang Xing, Xin Peng, Mingwei Liu, and Xuejiao Zhao. 2018. Improving API Caveats Accessibility by Mining API Caveats Knowledge Graph. In 2018 IEEE International Conference on Software Maintenance and Evolution (ICSME). 183–193. DOI: 10.1109/ICSME.2018.00028
Li Li, Jun Gao, Tegawendé F. Bissyandé, Lei Ma, Xin Xia, and Jacques Klein. 2018. Characterising deprecated Android APIs (MSR ’18). Association for Computing Machinery, New York, NY, USA, 254–264. DOI: 10.1145/3196398.3196419
Ruishi Li, Yunfei Yang, Jinghua Liu, Peiwei Hu, and Guozhu Meng. 2022. The inconsistency of documentation: a study of online C standard library documents. Cybersecurity 5 (07 2022), 14. DOI: 10.1186/s42400-022-00118-9
Meherun Nesa Lucky, Marco Cremaschi, Barbara Lodigiani, Antonio Menolascina, and Flavio De Paoli. 2016. Enriching API Descriptions by Adding API Profiles Through Semantic Annotation. In Service-Oriented Computing, Quan Z. Sheng, Eleni Stroulia, Samir Tata, and Sami Bhiri (Eds.). Springer International Publishing, Cham, 780–794.
Michael Meng, Stephanie Steinhardt, and Andreas Schubert. 2018. Application Programming Interface Documentation: What Do Software Developers Want? Journal of Technical Writing and Communication 48 (07 2018), 295–330. DOI: 10.1177/0047281617721853
Michael Meng, Stephanie M. Steinhardt, and Andreas Schubert. 2020. Optimizing API Documentation: Some Guidelines and Effects. In Proceedings of the 38th ACM International Conference on Design of Communication (Denton, TX, USA) (SIGDOC ’20). Association for Computing Machinery, New York, NY, USA, Article 24, 11 pages. DOI: 10.1145/3380851.3416759
Michał Michalski, Piotr Kosko, Dawid Juszczak, and Hobum Kwon. 2020. EWIDL: Single-Source Web API Documentation Management System. In 2020 IEEE International Conference on Software Maintenance and Evolution (ICSME). 723–726. DOI: 10.1109/ICSME46990.2020.00081
Mathieu Nassif, Zara Horlacher, and Martin P. Robillard. 2022. Casdoc: Unobtrusive Explanations in Code Examples. In 2022 IEEE/ACM 30th International Conference on Program Comprehension (ICPC). 631–635. DOI: 10.1145/3524610.3527730
Andy Neumann, Nuno Laranjeiro, and Jorge Bernardino. 2021. An Analysis of Public REST Web Service APIs. IEEE Transactions on Services Computing 14, 4 (2021), 957–970. DOI: 10.1109/TSC.2018.2847344
Kristian Nybom, Adnan Ashraf, and Ivan Porres. 2018. A Systematic Mapping Study on API Documentation Generation Approaches. In 2018 44th Euromicro Conference on Software Engineering and Advanced Applications (SEAA). 462–469. DOI: 10.1109/SEAA.2018.00081
Rahul Pandita, Kunal Taneja, Laurie Williams, and Teresa Tung. 2016. ICON: Inferring Temporal Constraints from Natural Language API Descriptions. In 2016 IEEE International Conference on Software Maintenance and Evolution (ICSME). 378–388. DOI: 10.1109/ICSME.2016.59
Xin Peng, Yifan Zhao, Mingwei Liu, Fengyi Zhang, Yang Liu, Xin Wang, and Zhenchang Xing. 2018. Automatic Generation of API Documentations for Open-Source Projects. In 2018 IEEE Third International Workshop on Dynamic Software Documentation (DySDoc3). 7–8. DOI: 10.1109/DySDoc3.2018.00010
Kai Petersen, Robert Feldt, Shahid Mujtaba, and Michael Mattsson. 2008. Systematic mapping studies in software engineering. In 12th international conference on evaluation and assessment in software engineering (EASE). BCS Learning & Development.
Hung Phan, Hoan Anh Nguyen, Tien N. Nguyen, and Hridesh Rajan. 2017. Statistical Learning for Inference between Implementations and Documentation. In 2017 IEEE/ACM 39th International Conference on Software Engineering: New Ideas and Emerging Technologies Results Track (ICSE-NIER). 27–30. DOI: 10.1109/ICSE-NIER.2017.9
Martin P. Robillard, Andrian Marcus, Christoph Treude, Gabriele Bavota, Oscar Chaparro, Neil Ernst, Marco Aurélio Gerosa, Michael Godfrey, Michele Lanza, Mario Linares-Vásquez, Gail C. Murphy, Laura Moreno, David Shepherd, and Edmund Wong. 2017. On-demand Developer Documentation. In 2017 IEEE International Conference on Software Maintenance and Evolution (ICSME). 479–483. DOI: 10.1109/ICSME.2017.17
Anand Ashok Sawant, Guangzhe Huang, Gabriel Vilen, Stefan Stojkovski, and Alberto Bacchelli. 2018. Why are Features Deprecated? An Investigation Into the Motivation Behind Deprecation. In 2018 IEEE International Conference on Software Maintenance and Evolution (ICSME). 13–24. DOI: 10.1109/ICSME.2018.00011
S. M. Sohan, Craig Anslow, and Frank Maurer. 2017. Automated example oriented REST API documentation at Cisco. In 2017 IEEE/ACM 39th International Conference on Software Engineering: Software Engineering in Practice Track (ICSE-SEIP). 213–222. DOI: 10.1109/ICSE-SEIP.2017.11
S M Sohan, Frank Maurer, Craig Anslow, and Martin P. Robillard. 2017. A study of the effectiveness of usage examples in REST API documentation. In 2017 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC). 53–61. DOI: 10.1109/VLHCC.2017.8103450
Donna Spencer. 2009. Card sorting: Designing usable categories. Rosenfeld Media.
Peng Sun, Chris Brown, Ivan Beschastnikh, and Kathryn T. Stolee. 2019. Mining Specifications from Documentation using a Crowd. In 2019 IEEE 26th International Conference on Software Analysis, Evolution and Reengineering (SANER). 275–286. DOI: 10.1109/SANER.2019.8668025
Yida Tao, Jiefang Jiang, Yepang Liu, Zhiwu Xu, and Shengchao Qin. 2021. Understanding performance concerns in the API documentation of data science libraries. In Proceedings of the 35th IEEE/ACM International Conference on Automated Software Engineering (Virtual Event, Australia) (ASE ’20). Association for Computing Machinery, New York, NY, USA, 895–906. DOI: 10.1145/3324884.3416543
Yuan Tian, Ferdian Thung, Abhishek Sharma, and David Lo. 2017. APIBot: Question answering bot for API documentation. In 2017 32nd IEEE/ACM International Conference on Automated Software Engineering (ASE). 153–158. DOI: 10.1109/ASE.2017.8115628
Gias Uddin, Foutse Khomh, and Chanchal K Roy. 2019. Towards Crowd-Sourced API Documentation. In 2019 IEEE/ACM 41st International Conference on Software Engineering: Companion Proceedings (ICSE-Companion). 310–311. DOI: 10.1109/ICSECompanion.2019.00129
Gias Uddin and Martin P. Robillard. 2015. How API Documentation Fails. IEEE Software 32, 4 (July 2015), 68–75. DOI: 10.1109/MS.2014.80. Acesso em: 28 maio 2025.
Daria Usova. 2023. Generating a Formalized REST API Definition Language for a Dynamic Framework Without Annotations Using Static Analysis Tools. In Proceedings of the 2023 IEEE International Conference on Engineering, Technology and Innovation (ICE/ITMC). 1710–1714. DOI: 10.1109/EDM58354.2023.10225100. Acesso em: 28 maio 2025.
Shujun Wang, Yongqiang Tian, and Dengcheng He. 2023. gDoc: Automatic Generation of Structured API Documentation. In Companion Proceedings of the ACM Web Conference 2023 (Austin, TX, USA) (WWW ’23 Companion). Association for Computing Machinery, New York, NY, USA, 53–56. DOI: 10.1145/3543873.3587310
Rahulkrishna Yandrapally, Saurabh Sinha, Rachel Tzoref-Brill, and Ali Mesbah. 2023. Carving UI Tests to Generate API Tests and API Specification. arXiv:2305.14692 [cs.SE] [link]
Jinqiu Yang, Erik Wittern, Annie T. T. Ying, Julian Dolby, and Lin Tan. 2018. Automatically Extracting Web API Specifications from HTML Documentation. arXiv:1801.08928 [cs.SE] [link]
Jinqiu Yang, Erik Wittern, Annie T. T. Ying, Julian Dolby, and Lin Tan. 2018. Towards extracting web API specifications from documentation. In Proceedings of the 15th International Conference on Mining Software Repositories (Gothenburg, Sweden) (MSR ’18). Association for Computing Machinery, New York, NY, USA, 454–464. DOI: 10.1145/3196398.3196411
Jingxuan Zhang, He Jiang, Zhilei Ren, Tao Zhang, and Zhiqiu Huang. 2021. Enriching API Documentation with Code Samples and Usage Scenarios from Crowd Knowledge. IEEE Transactions on Software Engineering 47, 6 (2021), 1299–1314. DOI: 10.1109/TSE.2019.2919304
Neng Zhang, Jian Wang, Keqing He, Zheng Li, and Yiwang Huang. 2019. Mining and clustering service goals for RESTful service discovery. Knowl. Inf. Syst. 58, 3 (March 2019), 669–700. DOI: 10.1007/s10115-018-1171-4
Neng Zhang, Ying Zou, Xin Xia, Qiao Huang, David Lo, and Shanping Li. 2023. Web APIs: Features, Issues, and Expectations – A Large-Scale Empirical Study of Web APIs From Two Publicly Accessible Registries Using Stack Overflow and a User Survey. IEEE Transactions on Software Engineering 49, 2 (2023), 498–528. DOI: 10.1109/TSE.2022.3154769
Yu Zhou, Ruihang Gu, Taolue Chen, Zhiqiu Huang, Sebastiano Panichella, and Harald Gall. 2017. Analyzing APIs Documentation and Code to Detect Directive Defects. In 2017 IEEE/ACM 39th International Conference on Software Engineering (ICSE). 27– 37. DOI: 10.1109/ICSE.2017.11
Yu Zhou, Changzhi Wang, Xin Yan, Taolue Chen, Sebastiano Panichella, and Harald Gall. 2020. Automatic Detection and Repair Recommendation of Directive Defects in Java API Documentation. IEEE Transactions on Software Engineering 46, 9 (2020), 1004–1023. DOI: 10.1109/TSE.2018.2872971
Adam Štšpánek, David Kuťák, Barbora Kozlíková, and Jan Byška. 2024. Interactive Diagrams for Software Documentation. In 2024 IEEE Working Conference on Software Visualization (VISSOFT). 12–23. DOI: 10.1109/VISSOFT64034.2024.00012
Publicado
27/10/2026
Como Citar
ALMEIDA, Gabriel Guimarães de; SOUZA, Mauricio Ronny de; FERREIRA, Fischer Jônatas.
API Documentation-Related Problems: A Systematic Mapping Study. In: BRAZILIAN SYMPOSIUM ON MULTIMEDIA AND THE WEB (WEBMEDIA), 32. , 2026, Lavras/MG.
Anais [...].
Porto Alegre: Sociedade Brasileira de Computação,
2026
.
p. 595-607.
DOI: https://doi.org/10.5753/webmedia.2026.30931.
