API Documentation with springdoc-openapi

 1// src/main/java/dev/mflash/guides/springdoc/Note.java
 2
 3public class Note {
 4
 5  private @Id long id;
 6  private String title;
 7  private String content;
 8
 9  // getters, setters, etc
10}

1// src/main/java/dev/mflash/guides/springdoc/NoteRepository.java
2
3public interface NoteRepository extends CrudRepository<Note, Long> {
4
5}

 1// src/main/java/dev/mflash/guides/springdoc/NoteController.java
 2
 3@RestController
 4@RequestMapping("/note")
 5public class NoteController {
 6
 7  private final NoteRepository repository;
 8
 9  public NoteController(NoteRepository repository) {
10    this.repository = repository;
11  }
12
13  @PutMapping
14  public List<Note> save(@RequestBody List<Note> notes) {
15    List<Note> savedNotes = new ArrayList<>();
16    repository.saveAll(notes).forEach(savedNotes::add);
17    return savedNotes;
18  }
19
20  @GetMapping
21  public List<Note> findAll() {
22    List<Note> savedNotes = new ArrayList<>();
23    repository.findAll().forEach(savedNotes::add);
24    return savedNotes;
25  }
26
27  @PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
28  public List<Note> upload(@RequestParam("data") MultipartFile csv) throws IOException {
29    List<Note> savedNotes = new ArrayList<>();
30    List<Note> notes = new BufferedReader(
31        new InputStreamReader(Objects.requireNonNull(csv).getInputStream(), StandardCharsets.UTF_8)).lines()
32        .map(Note::parseNote).collect(Collectors.toList());
33    repository.saveAll(notes).forEach(savedNotes::add);
34    return savedNotes;
35  }
36
37  @DeleteMapping("/{id}")
38  public boolean delete(@PathVariable("id") long id) {
39    repository.deleteById(id);
40    return true;
41  }
42}

1// src/main/java/dev/mflash/guides/springdoc/NoteController.java
2
3@Tag(name = "Note", description = "Endpoints for CRUD operations on notes")
4public class NoteController {
5
6  // rest of the code
7}

 1// src/main/java/dev/mflash/guides/springdoc/Launcher.java
 2
 3public @SpringBootApplication class Launcher {
 4
 5  public static void main(String[] args) {
 6    SpringApplication.run(Launcher.class, args);
 7  }
 8
 9  public @Bean OpenAPI noteAPI() {
10    return new OpenAPI()
11        .info(
12            new Info()
13                .title("Note API")
14                .description("A CRUD API to demonstrate Springdoc integration")
15                .version("0.0.1-SNAPSHOT")
16                .license(
17                    new License().name("MIT").url("https://opensource.org/licenses/MIT")
18                )
19        );
20  }
21}

 1// src/main/java/dev/mflash/guides/springdoc/NoteService.java
 2
 3@Tag(name = "Note", description = "Endpoints for CRUD operations on notes")
 4public @Service class NoteService {
 5
 6  private final NoteRepository repository;
 7
 8  public NoteService(NoteRepository repository) {
 9    this.repository = repository;
10  }
11
12  public List<Note> save(List<Note> notes) {
13    List<Note> savedNotes = new ArrayList<>();
14    repository.saveAll(notes).forEach(savedNotes::add);
15    return savedNotes;
16  }
17
18  public List<Note> findAll() {
19    List<Note> savedNotes = new ArrayList<>();
20    repository.findAll().forEach(savedNotes::add);
21    return savedNotes;
22  }
23
24  public List<Note> upload(Part csv) throws IOException {
25    List<Note> savedNotes = new ArrayList<>();
26    List<Note> notes = new BufferedReader(
27        new InputStreamReader(csv.getInputStream(), StandardCharsets.UTF_8)).lines()
28        .map(Note::parseNote).collect(Collectors.toList());
29    repository.saveAll(notes).forEach(savedNotes::add);
30    return savedNotes;
31  }
32
33  public boolean delete(@Parameter(in = ParameterIn.PATH) long id) {
34    repository.deleteById(id);
35    return true;
36  }
37}

 1// src/main/java/dev/mflash/guides/springdoc/NoteController.java
 2
 3public @Controller class NoteController {
 4
 5  private final NoteService service;
 6
 7  public NoteController(NoteService service) {
 8    this.service = service;
 9  }
10
11  public ServerResponse save(ServerRequest request) throws ServletException, IOException {
12    final List<Note> newNotes = request.body(new ParameterizedTypeReference<>() {});
13    return ServerResponse.ok().contentType(APPLICATION_JSON).body(service.save(newNotes));
14  }
15
16  public ServerResponse findAll(ServerRequest request) {
17    return ServerResponse.ok().contentType(APPLICATION_JSON).body(service.findAll());
18  }
19
20  public ServerResponse upload(ServerRequest request) throws IOException, ServletException {
21    Part csv = request.servletRequest().getPart("data");
22    return ServerResponse.ok().contentType(APPLICATION_JSON).body(service.upload(csv));
23  }
24
25  public ServerResponse delete(ServerRequest request) {
26    long id = Long.parseLong(request.pathVariable("id"));
27    return ServerResponse.ok().contentType(APPLICATION_JSON).body(service.delete(id));
28  }
29
30  @RouterOperations({
31    @RouterOperation(path = "/note", method = PUT, beanClass = NoteService.class, beanMethod = "save"),
32    @RouterOperation(path = "/note", method = GET, beanClass = NoteService.class, beanMethod = "findAll"),
33    @RouterOperation(path = "/note", method = POST,
34        operation = @Operation(
35            operationId = "multipart-upload",
36            requestBody = @RequestBody(required = true, description = "Upload a csv of notes"),
37            responses = @ApiResponse()
38        ),
39        beanClass = NoteService.class, beanMethod = "upload"),
40    @RouterOperation(path = "/note/{id}", method = DELETE, beanClass = NoteService.class, beanMethod = "delete")
41  })
42  public @Bean RouterFunction<ServerResponse> routes() {
43    return route()
44        .nest(RequestPredicates.path("/note"),
45            builder -> builder.PUT("/", this::save)
46                .GET("/", this::findAll)
47                .POST("/", RequestPredicates.accept(MULTIPART_FORM_DATA), this::upload)
48                .DELETE("/{id}", this::delete).build())
49        .build();
50  }
51}

 1// src/main/java/dev/mflash/guides/springdoc/Launcher.java
 2
 3public @SpringBootApplication class Launcher {
 4
 5  public static void main(String[] args) {
 6    SpringApplication.run(Launcher.class, args);
 7  }
 8
 9  public @Bean OpenAPI noteAPI() {
10    return new OpenAPI()
11        .info(
12            new Info()
13                .title("Note API")
14                .description("A CRUD API to demonstrate Springdoc integration")
15                .version("0.0.1-SNAPSHOT")
16                .license(
17                    new License().name("MIT").url("https://opensource.org/licenses/MIT")
18                )
19        );
20  }
21
22  public @Bean OpenApiCustomiser openApiCustomiser() {
23    return openApi -> openApi.getPaths()
24        .values().stream().flatMap(pathItem -> pathItem.readOperations().stream())
25        .forEach(operation -> {
26          if ("multipart-upload".equals(operation.getOperationId())) {
27            operation.getRequestBody()
28                .setContent(
29                    new Content().addMediaType(
30                        MediaType.MULTIPART_FORM_DATA_VALUE,
31                        new io.swagger.v3.oas.models.media.MediaType()
32                            .schema(new ObjectSchema().addProperties("data", new FileSchema()))
33                    )
34                );
35          }
36        });
37  }
38}