Leveraging LLMs to Generate formal and standardized Specifications from Heterogeneous REST API Docs
In modern software development, Representational State Transfer (REST) APIs play a
pivotal role in enabling communication between services and systems. A REST API’s
documentation is typically a structured textual explanation of its usage. This typically
includes details about endpoints, request/response formats, parameters, authenticati-
on, error codes, and example calls. It helps developers understand how to use the API
e?ectively, speeding up integration and reducing the need for support. It also ensures
consistency in design, facilitates testing and debugging, and supports onboarding of new
team members. Well-documented APIs also promote adoption and enhance collaboration
across development teams. Standards such as the OpenAPI Specification (OAS) [1, 2]
o?er a machine-readable format for describing REST APIs, enabling various tools [3, 4, 5,
6, 7, 8] for validation, client generation, testing, and more due to its predefined structure.
However, despite their importance, many APIs are documented informally – spread across
HTML pages, PDFs, wikis, and other unstructured or semi-structured formats. Even if a
formal description standard is in use, it is often the case that the description is incomplete,
out of date or has faulty parts. The process of manually converting legacy or informal
documentation into standardized specifications is both time-consuming and prone to
errors. This problem has also been observed in the context of APIs, such as those utilized
by GitLab [9]. These disparate and often inconsistent or faulty documentation sources
hinder automation, increase the learning curve for developers, and pose challenges for
integration, testing, and maintenance.
Recent advances in large language models (LLMs) present a unique opportunity to au-
tomate this transformation. By understanding and interpreting diverse documentation
formats, LLMs could be a possible bridge between human-written API descriptions and
formal specifications. This thesis will explore the feasibility and e?ectiveness of using
existing LLMs to convert heterogeneous REST API documentation data sources into a
standardized format that serves as a single source of truth. The resulting specifications
should be machine-readable and reflect the real relationships between resources. This
includes dependencies such as schema references, path hierarchies, foreign keys, shared
identifiers, and embedded resources. Additionally, consistent use of tags, naming con-
ventions, and operation design helps expose the semantic and functional links between
entities.
Referenzen
[1] API Documentation & Design Tools for Teams | Swagger. URL: swagger.io
[2] OpenAPI Specification - Version 3.1.0 | Swagger. URL: swagger.io/specification/
[3] swagger-api/swagger-codegen. 30. Apr. 2025. URL: https://github.com/swagger-api/swagger-codegen
[4] HOME-programming-pub/ObST. 5. Sep. 2024. URL: github.com/HOME-programming-pub/ObST
[5] Benjamin Kissmann: Automatisiertes Testen von RESTful Webservices zur Validierung
von Claim-basierten Berechtigungskonzepten mittels der OpenAPI-Dokumentation.
Hochschulbibliothek, 皇冠足球体育_足球比分直播￥中国竞彩网. 14. Juli 2021. DOI: 10.25673/37346.
[6] microsoft/restler-fuzzer. 30. Apr. 2025. URL: github.com/microsoft/restler-fuzzer
[7] Deriving Semantics-Aware Fuzzers from Web API Schemas. Dez. 2021
[8] Postman: The World’s Leading API Platform | Sign Up for Free. Postman API Platform. URL: www.postman.com
[9] Investigate and develop tooling for OpenAPI v3 API documentation (#519959) · Issues
· GitLab.org / GitLab · GitLab. GitLab. 17. Feb. 2025. URL: https://gitlab.com/gitlab-org/gitlab/-/issues/519959