2. Create-a-resource.md

Create our first resource

Now, your application is ready to use, you will work on the API itself.

The goal, here, is to define an API for follow students and teachers for an online personal course. So, the specifications are:

• Teachers are defined by their Firstname and Lastname
• Students are defined by their Firstname, Lastname and a birth date
• A student can only have one teacher as referent
• We want to be able to retrieve a specific student or a student list.

Define our first resource

Nb: The following code is written with the openapi 2.X specification, to know how to do with a 3+ spec please refer to the OpenApi specifications.

We starting with the "info" part. Nothing special here, except for the basePath value. The basePathshould stay as is when using JHipster, because it not need extra configuration to be exposed into the swagger-ui, and it follows the JHipster guideline. For your own purpose you could overwrite this value. Be sure to update the JHipster configuration in this case.

swagger: '2.0'
info:
  description: 'This is a sample JHipster application with OpenApi option.'
  version: '1.0.0'
  title: 'workshop-openapi'
  contact:
    email: '[email protected]'
  license:
    name: 'Apache 2.0'
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: localhost:8080
basePath: '/api/v1'

Add the teacher definition

Add the end of the file, add a descriptions section to manage our objects.

definitions:
  teacher:
    type: 'object'
    properties:
      id:
        type: 'integer'
        format: 'int64'
      firstname:
        type: 'string'
      lastname:
        type: 'string'

Add the student definition

  student:
    type: 'object'
    properties:
      id:
        type: 'integer'
        format: 'int64'
      firstname:
        type: 'string'
      lastname:
        type: 'string'
      birthday:
        type: 'string'
        format: 'date'
      teacher:
        $ref: '#/definitions/teacher'

$ref is used to link objects to other. A student has one and only one teacher linked to.

Add a student array definition

For collection purposes, we have to define a student array. You just have to define a new entry in the definition part, like this:

  students:
    type: 'array'
    items:
      $ref: '#/definitions/student'

Add path definitions

Now you have both teacher and student objects defined, add a path definition.

Below the definitions part, add a path part:

paths:
  /students:
    get:
      summary: 'get all students'
      operationId: 'getAllStudents'
      responses:
        200:
          description: 'successful operation'
          schema:
            $ref: '#/definitions/students'
      produces:
        - application/json
  /students/{id}:
    get:
      summary: 'get an student'
      operationId: 'getStudent'
      parameters:
        - name: 'id'
          required: true
          type: 'integer'
          in: 'path'
      responses:
        200:
          description: 'successful operation'
          schema:
            $ref: '#/definitions/student'
      produces:
        - application/json

/students return a student collection, schema ref to the array definition; /student/{id} return a student by his id, schema` ref to object definition.

Final result

At this point of the workshop you should have an api.yaml like this:

# API-first development with OpenAPI
# This file will be used at compile time to generate Spring-MVC endpoint stubs using openapi-generator
swagger: '2.0'
info:
  description: 'This is a sample JHipster application with OpenApi option.'
  version: '1.0.0'
  title: 'offersOpenApi'
  contact:
    email: '[email protected]'
  license:
    name: 'Apache 2.0'
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: localhost:8080
basePath: '/api/v1'
schemes:
  - 'http'
paths:
  /students:
    get:
      summary: 'get all students'
      operationId: 'getAllStudents'
      responses:
        200:
          description: 'successful operation'
          schema:
            $ref: '#/definitions/students'
      produces:
        - application/json
  /students/{id}:
    get:
      summary: 'get an student'
      operationId: 'getStudent'
      parameters:
        - name: 'id'
          required: true
          type: 'integer'
          in: 'path'
      responses:
        200:
          description: 'successful operation'
          schema:
            $ref: '#/definitions/student'
      produces:
        - application/json
definitions:
  student:
    type: 'object'
    properties:
      id:
        type: 'integer'
        format: 'int64'
      firstname:
        type: 'string'
      lastname:
        type: 'string'
      birthday:
        type: 'string'
        format: 'date'
      teacher:
        $ref: '#/definitions/teacher'
  teacher:
    type: 'object'
    properties:
      id:
        type: 'integer'
        format: 'int64'
      firstname:
        type: 'string'
      lastname:
        type: 'string'
  students:
    type: 'array'
    items:
      $ref: '#/definitions/student'

Copy and past the result in the Swagger editor and check the result match with your needs.

Generate sources

Go back into the terminal and generate classes with this command:

./mvnw generate-sources

When it's done, the generated classes are available in the target folder. target/

Nb. Your IDE, probably, ignore the "target" folder by default. Be sure to reload the maven config to detect the generated classes.

When using Eclipse or VSCode

./mvnw eclipse:clean eclipse:eclipse

When using IntelliJ

./mvnw idea:idea

Re-run the application and check the swagger-ui

If your application is still running, stop and relaunch it with the maven command.

./mvnw

Go into the admin menu and select API entry. You should, now, see our student API in the swagger UI.

Let's mock this API ! >>> next