Document one REST endpoint with springdoc

[blcham]

The goal of the task is to agree on how to document REST endpoints. Inspiration can be taken from https://github.com/kbss-cvut/termit.

A/C:

• one endpoint is chosen, and it is annotated
• the documentation of REST API is accessible from the application and docker-compose services and how to access it is described in README
• the documentation of the endpoint is discussed and approved here
• it is possible to run those services from the springdoc documentation [1]

[palagdan]

@blcham
For documentation, we can use Springdoc annotations such as @operation and @ApiResponses. For example, let's take a look at ComponentController:

 @Operation(summary = "Create a new component")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "201", description = "Component created successfully"),
        @ApiResponse(responseCode = "400", description = "Invalid input")
    })
    @ResponseStatus(HttpStatus.CREATED)
    @PostMapping(consumes = {MediaType.APPLICATION_JSON_VALUE, JsonLd.MEDIA_TYPE})
    public Component create(@RequestBody Component component) {
        log.info("> create - {}", component);
        repositoryService.persist(component);
        return component;
    }

  @Operation(summary = "Retrieve all components")
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "Successfully retrieved all components")
    })
    @GetMapping(produces = {JsonLd.MEDIA_TYPE, MediaType.APPLICATION_JSON_VALUE})
    public List<Component> findAll() {
        return repositoryService.findAll();
    }

[blcham]

@palagdan i updated A/C

for [1] u might need something like
@Operation(security = {@SecurityRequirement(name = "bearer-key")

[palagdan]

Could you explain the last A/C to me?
It is possible to run those services from the Springdoc documentation [1]
Which services are being referred to?

[blcham]

I would like to have the web form generated by springdoc ready as much as possible to to execute any of any concrete REST API endpoint.

I assume it is possible to execute annotated REST API endpoints from there -- am i right?

[palagdan]

Yes, you are right!