public interface PersonResource {
    @GET
    @Path("/{id}")
    @Produces(MediaType.APPLICATION_JSON)
    Person get(@PathParam("id")long id);

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    Person add(Person person);

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    List<Person> findByName(@QueryParam("name") String name);
}

@ApplicationScoped
@Path("persons")
public class PersonResourceImpl implements PersonResource  {

    private Map<Long, Person> personMap = new ConcurrentHashMap<>();

    @PostConstruct
    public void init() {
        personMap.put(1L, new Person(1L, "taro", 12));
        personMap.put(2L, new Person(2L, "hanko", 9));
        personMap.put(3L, new Person(3L, "bob", 15));
    }

    @Override
    public Person get(long id) {
        if (!personMap.containsKey(id)) {
            throw new PersonException(CauseError.NOT_FOUND);
        }
        return personMap.get(id);
    }

    @Override
    public Person add(Person person) {
        // name の重複は許可しない
        personMap.values().stream()
                .filter(p -> p.getName().equals(person.getName()))
                .findAny()
                .ifPresent(p -> {
                    throw new PersonException(CauseError.CONFLICT);
                });
        // Personの登録
        var nextId = personMap.keySet().stream().max(Long::compareTo).get() + 1;
        var newPerson = person.withId(nextId);
        personMap.put(nextId, newPerson);
        return newPerson;
    }

    @Override
    public List<Person> findByName(String name) {
        return personMap.values().stream()
                .filter(p -> p.getName().startsWith(name))
                .collect(Collectors.toList());
    }
}

# Clone this repository
git clone https://github.com/extact-io/contrarian-microprofile-sample.git
# Go into the sample
cd contrarian-microprofile-sample/03-openapi/01_before
# build application
mvn clean package
# start application
java -jar target/openapi-sample.jar

# 該当あり
curl -X GET http://localhost:7001/api/persons/1 -w ':%{http_code}\n'
{"age":12,"id":1,"name":"taro"}:200

# 該当なし
curl -X GET http://localhost:7001/api/persons/9 -w ':%{http_code}\n'
Not Found:404

# toshioを登録
curl -X POST -H "Content-Type: application/json" -d '{"id":null,"name":"toshio","age":20}' http://localhost:7001/api/persons -w ':%{http_code}\n'
{"age":20,"id":4,"name":"toshio"}:200

# toshioを再度登録（重複エラー）
curl -X POST -H "Content-Type: application/json" -d '{"id":null,"name":"toshio","age":20}' http://localhost:7001/api/persons -w ':%{http_code}\n'
Conflict:409

# nameが't'から始まるpersonを検索（該当複数）
curl -X GET http://localhost:7001/api/persons?name=t -w ':%{http_code}\n'
[{"age":12,"id":1,"name":"taro"},{"age":20,"id":4,"name":"toshio"}]:200

# nameが'x'から始まるpersonを検索（該当なし）
curl -X GET http://localhost:7001/api/persons?name=x -w ':%{http_code}\n'
[]:200

curl -X GET http://localhost:7001/openapi

info:
  title: Generated API
  version: '1.0'
openapi: 3.0.3
paths:
  /persons:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: OK
    get:
      parameters:
      -
        in: query
        name: name
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:  {}
                type: array
          description: OK
  /persons/{id}:
    get:
      parameters:
      -
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: OK

@OpenAPIDefinition(info =
    @Info(
        title = "MicroProfile OpneAPI Sample", 
        version = "0.0.1-SNAPSHOT", 
        contact = 
            @Contact(
                name = "課外活動", 
                url = "https://extact-io.github.io/")))
@ApplicationScoped
@ApplicationPath("api")
public class PersonApplication extends Application {
    @Override
    public Set<Class<?>> getClasses() {
        return Set.of(
                PersonResourceImpl.class,
                PersonExceptionMapper.class);
    }
}

# build application
mvn clean package
# start application
java -jar target/openapi-sample.jar
# get APISpec
curl -X GET http://localhost:7001/openapi

info:
  contact:
    name: 課外活動
    url: https://extact-io.github.io/
  title: MicroProfile OpneAPI Sample
  version: 0.0.1-SNAPSHOT

@GET            // JAX-RS
@Path("/{id}")  // JAX-RS
@Produces(MediaType.APPLICATION_JSON) // JAX-RS
@Operation( // MP-OpneAPI
    operationId = "get", 
    summary = "Person情報を取得する", 
    description = "指定されたIDに対するPerson情報を取得する")
@Parameter( // MP-OpneAPI
    name = "id", 
    description = "PersonのインスタンスID", 
    required = true, 
    schema = @Schema(
        implementation = Long.class, 
        minimum = "0", 
        maximum = "9999999"))
@APIResponse( // MP-OpneAPI
    responseCode = "200", 
    description = "成功")
@APIResponse( // MP-OpneAPI
    responseCode = "404", 
    description = "該当なし", 
    content = @Content(
        mediaType = "text/plan", 
        example = "Not Found"))
Person get(@PathParam("id")long id);

paths:
  /api/persons/{id}:  # 1.
    get:              # 2.
      operationId: get  # 3.
      summary: Person情報を取得する # 3.
      description: 指定されたIDに対するPerson情報を取得する # 3.
      parameters: # 4.
      -
        description: PersonのインスタンスID
        in: path
        name: id
        required: true
        schema: # 5.
          format: int64
          maximum: 9999999
          minimum: 0
          type: integer
      responses:  # 6.
        '200':    # 7.
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '404':    # 8.
          description: 該当なし
          content:
            text/plan:
              example: Not Found
components: # 9.
  schemas:  # 9.
    Person: # 10.
      properties:
        age:
          format: int32
          type: integer
        id:
          format: int64
          type: integer
        name:
          type: string
      type: object

@POST // JAX-RS
@Consumes(MediaType.APPLICATION_JSON) // JAX-RS
@Produces(MediaType.APPLICATION_JSON) // JAX-RS
@Operation( // MP-OpenAPI
    operationId = "add", 
    summary = "Person情報を登録する", 
    description = "IDは登録時に自動で採番する")
@Parameter( // MP-OpenAPI
    name = "person", 
    description = "登録するPersonインスタンス", 
    required = true)
@APIResponse( // MP-OpenAPI
    responseCode = "200", 
    description = "成功。IDには採番した値を設定する")
@APIResponse( // MP-OpenAPI
    responseCode = "409", 
    description = "既に使用されているためnameのため重複エラー", 
    content = @Content(
        mediaType = "text/plan", example = "Conflict"))
Person add(Person person);

/api/persons:
  post:
    operationId: add
    summary: Person情報を登録する
    description: IDは登録時に自動で採番する
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Person'
    responses:
      '200':
        description: 成功。IDには採番した値を設定する
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Person'
      '409':
        description: 既に使用されているためnameのため重複エラー
        content:
          text/plan:
            example: Conflict

@GET  // JAX-RS
@Produces(MediaType.APPLICATION_JSON) // JAX-RS
@Operation( // MP-OpenAPI
    operationId = "findByName", 
    summary = "Person情報を検索する", 
    description = "QueryStringで指定されたnameに前方一致するPerson情報を検索する")
@Parameter( // MP-OpenAPI
    name = "name", 
    description = "検索するnameの値", 
    required = true)
@APIResponse( // MP-OpenAPI
    responseCode = "200", 
    description = "成功。該当なしの場合は空リストで返却する")
List<Person> findByName(@QueryParam("name") String name);

/api/persons:
  get:
    operationId: findByName
    summary: Person情報を検索する
    description: QueryStringで指定されたnameに前方一致するPerson情報を検索する
    parameters:
    -
      description: 検索するnameの値
      in: query
      name: name
      required: true
      schema:
        type: string
    responses:
      '200':
        description: 成功。該当なしの場合は空リストで返却する
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/Person'
              type: array

@Schema(description = "Person情報") // MP-OpenAPI
@NoArgsConstructor  // Lombok
@AllArgsConstructor // Lombok
@Setter @Getter     // Lombok
public class Person {
    @With // Lombok
    @Schema(  // MP-OpenAPI
        description = "インスタンスID", 
        implementation = Long.class, 
        minimum = "0", 
        maximum = "9999999")
    private Long id;
    @Schema(  // MP-OpenAPI
        description = "名前", 
        required = true,  
        minLength = 1, 
        maxLength = 10)
    private String name;
    @Schema(  // MP-OpenAPI
        description = "年齢", 
        required = true,  
        implementation = Integer.class, 
        minimum = "0", 
        maximum = "199")
    private int age;
}

components:
  schemas:
    Person:
      type: object
      description: Person情報
      required:
      - name
      - age
      properties:
        id:
          description: インスタンスID
          format: int64
          maximum: 9999999
          minimum: 0
          type: integer
        name:
          description: 名前
          maxLength: 10
          minLength: 1
          type: string
        age:
          description: 年齢
          format: int32
          maximum: 199
          minimum: 0
          type: integer