Improving the Quality of OpenAPI Specifications Using TypeScript Types and Annotations
Motivation:
The rise of Enterprise APIs and the API economy have increased the demand for well documented APIs on the internet. However, many software engineering teams intend to develop their product following agile software development principles and therefore explicitly putting “working software over comprehensive documentation” (1). Even when documentation is an explicit requirement, many REST APIs don’t live up to expectations in practice in very basic ways (2). In this thesis, we try to consolidate best practices of API documentation with agile software development through automated integration into the operations process.
Research Questions:
1. How/What can API documentation for Web APIs be extracted from TypeScript Types and Annotations?
2. Which additional elements of good API documentation may be created and/or verified automatically within the continuous development process.
3. How do developers perceive the process of automated documentation extracted from TypeScript Types and Annotations?
Keywords: API, API Economy, API Management, OpenAPI, CI/CD, Continuous delvelopment
Bibliography:
1. Kent M. Beck, Mike Beedle, Arie van Bennekum, Alistair Cockburn, Ward Cunningham, Martin Fowler, James Grenning, Jim Highsmith, Andy Hunt, Ron Jeffries, Jon Kern, Brian Marick, R. C. Martin, Steve J. Mellor, Ken Schwaber, Jeff Sutherland, and Dave Thomas. Manifesto for agile software development. 2013.
2. Masaki Hosono, Hironori Washizaki, Yoshiaki Fukazawa, and Kiyoshi Honda. An empirical study on the reliability of the web api document. In 2018 25th Asia-Pacific Software Engineering Conference (APSEC), pages 715–716. IEEE, 2018.