openapi: 3.0.0 (1)
info: (2)
  description: This is a library API
  version: 1.0.0
  title: Library
  license:
    name: Apache-2.0
    url: "https://www.apache.org/licenses/LICENSE-2.0.html"
tags: (3)
  - name: books
    description: Search for books and add new ones

paths:

  /search:
    get: (1)
      tags: 
        - books (2)
      summary: Search for a book
      operationId: search (3)
      parameters: (4)
        - name: book-name
          in: query
          schema: 
            type: string
            minLength: 3 (5)
        - name: author-name
          in: query
          schema: 
            type: string
      responses: (6)
        "200": (7)
          description: Success
          content:
            "applicaton/json":
              schema:
                type: array, 
                items: 
                  $ref: "#/components/schemas/BookInfo"
        "400": (8)
          description: Bad Request

  /add:
    post: (1)
      tags: [books]
      summary: Add a new book
      operationId: addBook
      requestBody: (2)
        required: true
        content:
          "application/json": 
            schema: 
              $ref: "#/components/schemas/BookInfo" (3)
      responses:
        "200":
          description: Success
        "400":
          description: Bad Request

components:
  schemas:
    BookInfo:
      title: Book Info (1)
      description: Object containg all the info about a book
      type: object
      properties: (2)
        name: {type: string}
        availability: {$ref: "#/components/schemas/BookAvailability"} (3)
        author: {type: string, minLength: 3}
        ISBN: {type: string, pattern: "[0-9]{13}"}
      required: ["name", "availability"]
    BookAvailability: (4)
      type: string
      enum: ["available", "not available", "reserved"]

<!-- Add the following to your annotationProcessorPaths element -->
<path>
    <groupId>io.micronaut.data</groupId>
    <artifactId>micronaut-data-processor</artifactId>
</path>
<dependency>
    <groupId>io.micronaut.data</groupId>
    <artifactId>micronaut-data-jdbc</artifactId>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>io.micronaut.sql</groupId>
    <artifactId>micronaut-jdbc-hikari</artifactId>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>mysql-connector-java</groupId>
    <artifactId>mysql</artifactId>
    <scope>runtime</scope>
</dependency>

datasources:
  default: (1)
    dialect: MYSQL
    driverClassName: ${JDBC_DRIVER:com.mysql.cj.jdbc.Driver} (2)

<dependency>
    <groupId>io.micronaut.flyway</groupId>
    <artifactId>micronaut-flyway</artifactId>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-mysql</artifactId>
    <scope>runtime</scope>
</dependency>

flyway:
  datasources:
    default:
      enabled: true (1)

CREATE TABLE book (
    id  BIGINT NOT NULL AUTO_INCREMENT UNIQUE PRIMARY KEY,
    name  VARCHAR(255) NOT NULL,
    availability  ENUM('available', 'reserved', 'not available') NOT NULL,
    author  VARCHAR(255),
    ISBN  CHAR(13)
);

INSERT INTO book
    (name, availability, author, ISBN)
VALUES
    ("Alice's Adventures in Wonderland",      "available",   "Lewis Caroll",   "9783161484100"),
    ("The Hitchhiker's Guide to the Galaxy",  "reserved",    "Douglas Adams",  NULL),
    ("Java Guide for Beginners",              "available",   NULL,             NULL);

package example.micronaut;

import example.micronaut.model.BookAvailability;
import io.micronaut.core.annotation.NonNull;
import io.micronaut.core.annotation.Nullable;
import io.micronaut.data.annotation.GeneratedValue;
import io.micronaut.data.annotation.Id;
import io.micronaut.data.annotation.MappedEntity;
import io.micronaut.data.annotation.MappedProperty;

import javax.validation.constraints.NotNull;

@MappedEntity("book") (1)
public class BookEntity {

    @Id (2)
    @GeneratedValue(GeneratedValue.Type.AUTO)
    private Long id;

    @NonNull
    @NotNull
    private String name;

    @NonNull
    @NotNull
    private BookAvailability availability;

    @Nullable
    private String author;

    @Nullable
    @MappedProperty("ISBN")
    private String isbn;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    @NonNull
    public BookAvailability getAvailability() {
        return availability;
    }

    public void setAvailability(@NonNull BookAvailability availability) {
        this.availability = availability;
    }

    @Nullable
    public String getIsbn() {
        return isbn;
    }

    public void setIsbn(@Nullable String isbn) {
        this.isbn = isbn;
    }

    @NonNull
    public String getName() {
        return name;
    }

    public void setName(@NonNull String name) {
        this.name = name;
    }

    @Nullable
    public String getAuthor() {
        return author;
    }

    public void setAuthor(@Nullable String author) {
        this.author = author;
    }
}

package example.micronaut;

import example.micronaut.model.BookAvailability;
import io.micronaut.core.annotation.NonNull;
import io.micronaut.data.jdbc.annotation.JdbcRepository;
import io.micronaut.data.model.query.builder.sql.Dialect;
import io.micronaut.data.repository.GenericRepository;
import io.micronaut.data.repository.jpa.JpaSpecificationExecutor;
import io.micronaut.data.repository.jpa.criteria.PredicateSpecification;

import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import java.util.List;

@JdbcRepository(dialect = Dialect.MYSQL) (1)
public interface BookRepository extends GenericRepository<BookEntity, Long>, (2)
        JpaSpecificationExecutor<BookEntity> { (3)

    @NonNull
    List<BookEntity> findAll(PredicateSpecification<BookEntity> spec);  (4)

    @NonNull
    List<BookEntity> findAll();


    @NonNull
    BookEntity save(@NonNull @NotBlank String name,
                    @NonNull @NotNull BookAvailability availability,
                    @NonNull @NotBlank String author,
                    @NonNull @NotBlank String isbn);
}

package example.micronaut;

import io.micronaut.core.annotation.NonNull;
import io.micronaut.data.repository.jpa.criteria.PredicateSpecification;

public class BookSpecifications {
    public static PredicateSpecification<BookEntity> nameLike(@NonNull String name) {
        return (root, criteriaBuilder) -> criteriaBuilder.like(root.get("name"), "%"+name+"%");
    }

    public static PredicateSpecification<BookEntity> authorLike(@NonNull String author) {
        return (root, criteriaBuilder) -> criteriaBuilder.like(root.get("author"), "%"+author+"%");
    }
}

private final BookRepository bookRepository; (1)

public BooksController(BookRepository bookRepository) { (1)
    this.bookRepository = bookRepository;
}

@ExecuteOn(TaskExecutors.IO) (1)
public List<BookInfo> search(
        @QueryValue(value="book-name") @Nullable @Size(min=3) String bookName,
        @QueryValue(value="author-name") @Nullable String authorName) {
    return searchEntities(bookName, authorName)
            .stream()
            .map(this::map) (5)
            .collect(Collectors.toList());
}

private BookInfo map(BookEntity entity) {
    BookInfo book = new BookInfo(entity.getName(), entity.getAvailability());
    book.setISBN(entity.getIsbn());
    book.setAuthor(entity.getAuthor());
    return book;
}

@NonNull
private List<BookEntity> searchEntities(@Nullable String name, @Nullable String author) { (2)
    if (StringUtils.isEmpty(name) && StringUtils.isEmpty(author)) {
        return bookRepository.findAll();
    } else if (StringUtils.isEmpty(name)) {
        return bookRepository.findAll(BookSpecifications.authorLike(author)); (3)

    } else  if (StringUtils.isEmpty(author)) {
        return bookRepository.findAll(BookSpecifications.nameLike(name));
    } else {
        return bookRepository.findAll(BookSpecifications.authorLike(author)
                .and(BookSpecifications.nameLike(name))); (4)
    }
}

@ExecuteOn(TaskExecutors.IO) (1)
@Status(OK) (2)
public void addBook(@Body @NotNull @Valid BookInfo bookInfo) {
    bookRepository.save(bookInfo.getName(), (3)
            bookInfo.getAvailability(),
            bookInfo.getAuthor(),
            bookInfo.getISBN());
}

import io.micronaut.context.annotation.Property;
import io.micronaut.context.annotation.Requires;
import io.micronaut.http.HttpRequest;
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Produces;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import jakarta.annotation.security.PermitAll;
import jakarta.inject.Inject;
import org.junit.jupiter.api.Test;
import javax.validation.Validator;

import static org.junit.jupiter.api.Assertions.*;

    @Inject
    Validator validator; (1)

    @Test
    public void nameTest() {
        BookInfo bookInfo = new BookInfo("Alice's Adventures in Wonderland", BookAvailability.AVAILABLE);
        assertTrue(validator.validate(bookInfo).isEmpty()); (2)

        bookInfo = new BookInfo(null, BookAvailability.AVAILABLE);
        assertFalse(validator.validate(bookInfo).isEmpty()); (3)
    }

    @Test
    public void availabilityTest() { (4)
        BookInfo bookInfo = new BookInfo("ALice's Adventures in Wonderland", BookAvailability.RESERVED);
        assertTrue(validator.validate(bookInfo).isEmpty());

        bookInfo = new BookInfo("Alice's Adventures in Wonderland", null);
        assertFalse(validator.validate(bookInfo).isEmpty());
    }

    @Test
    public void authorTest() {
        BookInfo bookInfo = new BookInfo("Alice's Adventures in Wonderland", BookAvailability.AVAILABLE)
                .author(null);
        assertTrue(validator.validate(bookInfo).isEmpty());

        bookInfo = new BookInfo("Alice's Adventures in Wonderland", BookAvailability.AVAILABLE)
                .author("Lewis Carroll");
        assertTrue(validator.validate(bookInfo).isEmpty()); (1)

        bookInfo = new BookInfo("Alice's Adventures in Wonderland", BookAvailability.AVAILABLE)
                .author("fo");
        assertFalse(validator.validate(bookInfo).isEmpty()); (2)
    }

    @Test
    public void ISBNTest() {
        BookInfo bookInfo = new BookInfo("Alice's Adventures in Wonderland", BookAvailability.AVAILABLE)
                .ISBN(null);
        assertTrue(validator.validate(bookInfo).isEmpty());

        bookInfo = new BookInfo("Alice's Adventures in Wonderland", BookAvailability.AVAILABLE)
                .ISBN("9783161484100");
        assertTrue(validator.validate(bookInfo).isEmpty()); (3)

        bookInfo = new BookInfo("Alice's Adventures in Wonderland", BookAvailability.AVAILABLE)
                .ISBN("9783161 84100");
        assertFalse(validator.validate(bookInfo).isEmpty()); (4)
    }

@Property(name = "spec.name", value = "BookInfoTest") (2)
@MicronautTest
public class BookInfoTest {

    @Inject
    @Client("/")
    HttpClient httpClient;

    @Test
    public void bookInfoJsonSerialization() {
        BookInfo requiredBookInfo = new BookInfo("Alice's Adventures in Wonderland", BookAvailability.AVAILABLE)
                .author("Lewis Carroll")
                .ISBN("9783161484100");

        BookInfo bookInfo = httpClient.toBlocking().retrieve(HttpRequest.GET("/bookinfo"), BookInfo.class); (5)
        assertEquals(requiredBookInfo, bookInfo);
    }

    @Requires(property = "spec.name", value = "BookInfoTest") (3)
    @Controller("/bookinfo") (1)
    static class BookInfoSerdeController {
        @PermitAll
        @Get
        BookInfo index() { (4)
            return new BookInfo("Alice's Adventures in Wonderland", BookAvailability.AVAILABLE)
                    .author("Lewis Carroll")
                    .ISBN("9783161484100");
        }
    }

package example.micronaut.controller;

import example.micronaut.model.BookAvailability;
import example.micronaut.model.BookInfo;
import io.micronaut.http.uri.UriBuilder;
import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.client.annotation.Client;
import io.micronaut.http.HttpStatus;
import io.micronaut.http.MutableHttpRequest;
import io.micronaut.http.HttpRequest;
import io.micronaut.http.HttpResponse;
import io.micronaut.core.type.Argument;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.assertEquals;
import jakarta.inject.Inject;
import java.util.List;

@MicronautTest (1)
public class BooksControllerTest {

    @Inject
    @Client("${context-path}")
    HttpClient client; (2)

    @Test
    void addBookClientApiTest() {
        BookInfo body = new BookInfo("Building Microservices", BookAvailability.AVAILABLE);
        body.setAuthor("Sam Newman");
        body.setISBN("9781492034025");
        HttpResponse<?> response = client.toBlocking()
                .exchange(HttpRequest.POST("/add", body)); (3)
        assertEquals(HttpStatus.OK, response.status()); (4)
    }

    @Test
    void searchClientApiTest() {
        HttpResponse<List<BookInfo>> response = client.toBlocking()
                .exchange(HttpRequest.GET(UriBuilder.of("/search")
                        .queryParam("book-name", "Guide")
                        .build()
                ), Argument.listOf(BookInfo.class)); (5)
        List<BookInfo> body = response.body(); (6)
        assertEquals(HttpStatus.OK, response.status());
        assertEquals(2, body.size()); (7)
    }
}

./mvnw test

sdk install java 22.3.r11-grl

sdk install java 22.3.r17-grl

gu install native-image

./mvnw package -Dpackaging=native-image

paths:
  /search:
    # ... #
  /add:
    post:
      # ... #
      security:
        - MyBasicAuth: [] (2)
components:
  schemas:
    # ... #
  securitySchemes:
    MyBasicAuth: (1)
      type: http
      scheme: basic

@Secured(SecurityRule.IS_AUTHENTICATED)
public Mono<Object> addBook( /* ... */ ){ /* ... */ }

java -jar openapi-generator-cli-XXX.jar generate \
    -g java-micronaut-client \
    -i library-definition.yaml \
    -o library-client \
    -p apiPackage=example.micronaut.api \
    -p modelPackage=example.micronaut.model \
    -p build=maven \
    -p test=junit

# ... #
servers:
  - url: 'http://my.website.com'

java -jar openapi-generator-cli-XXX.jar generate \
    -g html2 \
    -i library-definition.yaml \
    -o html-docs