
The rapid adoption of modern web architectures (i.e., REST APIs) relies on clear and accurate documentation. The OpenAPI Specification (OAS) standard is widely adopted for this purpose, as it is machine-readable and provides a range of API-related fields. However, maintaining high-quality documentation is complex, as the frequent omission of important information significantly hinders the effectiveness of testing tools and API understanding. To address this problem, we introduce OASQuali, a tool that quantifies OAS quality across five dimensions: format, version, metadata, servers, and descriptions/examples. We conduct a large-scale empirical evaluation with 2,529 public specifications. Our results reveal a mean documentation quality of 67.11%. While aggregate quality is independent of API size, we identify a systemic "semantic gap" in large-scale implementations: As APIs enlarge, they become more up-to-date with OAS versions (53.10% -> 88.00%). However, the quality of their descriptions and examples drastically decreases (42.18% -> 24.00%). Notably, the absence of parameter examples in 86.95% of specifications represents a major bottleneck for operational clarity. OASQuali provides a rigorous framework for revealing these deficiencies, paving the way for more thoroughly documented web services.
REST APIs, OpenAPI Specification, Automated Analysis, Quality Metrics
REST APIs, OpenAPI Specification, Automated Analysis, Quality Metrics
| selected citations These citations are derived from selected sources. This is an alternative to the "Influence" indicator, which also reflects the overall/total impact of an article in the research community at large, based on the underlying citation network (diachronically). | 0 | |
| popularity This indicator reflects the "current" impact/attention (the "hype") of an article in the research community at large, based on the underlying citation network. | Average | |
| influence This indicator reflects the overall/total impact of an article in the research community at large, based on the underlying citation network (diachronically). | Average | |
| impulse This indicator reflects the initial momentum of an article directly after its publication, based on the underlying citation network. | Average |
