Spring Boot REST-rajapinnan automaattinen dokumentointi

Abstract

Opinnäytetyön tarkoituksena oli paikata Spring Boot -asiakasprojektin OpenAPI-dokumentaation puutteita sekä kehittää menetelmiä ehkäistä virheellisen OpenAPI-dokumentin tuottamista. Opinnäytetyössä haluttiin selvittää, kuinka voidaan hyödyntää muihin tarkoituksiin käytettyjä Java-annotaatioita ja muita kielen ominaisuuksia dokumentaation tuottamisessa.

Yhtenä tavoitteena oli tutkia, millä keinoilla voidaan dokumentoida rooli- ja attribuuttipohjaista pääsynhallintaa sekä rajapinnan virhetilanteita vaivattomammin.

Opinnäytetyön raportin tarkoituksena oli toimia resurssina kehittäjille, jotka ovat kiinnostuneita Spring Boot REST-rajapintojen dokumentoinnista. Opinnäytetyön raportti toivottavasti auttaa kehittäjää saavuttamaan perustason ymmärrysksen OpenAPIsta ja siitä, kuinka rajapintadokumentaatio voidaan tuottaa Spring Boot -sovelluskehykselle.

Työn tuloksena syntyi OpenAPI-dokumentin tuottamiseen komponentteja, joilla laajennetaan Springdoc-kirjaston tarjoamia oletustoteuksia. Nämä komponentit pystyvät tuottamaan tyypeiltä tarkemman sekä tarkemmin spesifikaatiota noudattavan OpenAPI-dokumentin. Aikaisemmin virheherkkien ja toistuvien sanomarakenteiden määrittely on uusien komponenttien myötä virheetöntä ja vaivatonta.

The purpose of the thesis was to overcome Spring Boot projects OpenAPI documentation shortcomings and develop methods to prevent the generation of incorrect OpenAPI document. The thesis wanted to find out how to make use of Java annotations and other language features, which are used for other purposes, for generating the documentation.

One of the goals was to investigate how to document role and attribute-based access control and error handling more effortlessly.

The aim of the thesis report was to serve as a resource for developers who are interested in documenting Spring Boot REST APIs. After reading the report, the developer will hopefully have a basic understanding of OpenAPI and how API documentation can be generated for the Spring Boot framework.

As a result of the thesis, components were created which extended the functionality provided by the Springdoc library. These components can produce OpenAPI document which is typed more strictly and follows the specification closely. With the new components previously error-prone and repetitive schema definitions are now flawless and effortless.