Feature/update readme and swagger

[southeo]

Updates swagger endpoints to include request and response schemas. Adds more descriptions.

OAS = openApi standard

Design decisions

Internal classes
We follow JsonApi, which is a pretty nested standard. I nest classes where possible because there are a lot of domain objects being created, and I try to minimize that. Now I understand why GBIF wound up with so many...

Why are some internal classes private and some are public
Usually, we need to access the internal classes in the requests to get the data. We don't need to do so for the responses, so those can be private.

Two @RequestBody annotations.
There are two RequestBody annotations. One from Spring, one from OAS. The OpenAPI @RequestBody annotation specifies what class to document the body as, but if it conflicts with the Spring @RequestBody, swagger prioritizes the Spring @RequestBody, which is the runtime type. So that means we can't have generic request objects anymore.

Why use the @Schema annotation at all

1. The @Schema Annotation is used for adding additional metadata
2. You can use it in conjunction with keywords like oneOf, which will be more useful in the Handle API, and it's good to be consistent across APIs
3. If you use generic Objects, OpenAPI will use the object in the @Schema implementation

Known issues

GET requests + request body The "schema" tab doesn't appear for GET requests that require a request body, (see /api/v1/annotation/batch as an example). This is because OpenApi doesn't want to encourage GET requests with a request body, so they don't support that.

[samleeflang]

Yes this is as expected. A lot more domain classes but not too complicated. Will help with readability of the docs. At some places we might need to add some description but let's start with this.

[samleeflang]

💺

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
44.6% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud