OpenAPI 3.0 Mock

When using light-codegen with OpenAPI 3.0 specification to generate light-rest-4j project, you can add examples into the specification definition so that the generated project will have handlers to return corresponding examples in response.

This is very useful for developers who are working on the service to verify that the service is working right off the generator.

Also, it is beneficial for client side developers as they can get a running service right off the specification to start their client side application development. Later on, they can switch to the real implementation to do the integration test.

This kind of support ensures that client side development and server side development can be running in parallel to speed up the overall delivery process. It is particularly useful with microservices architecture as each team only focus on their service but use other teams mock services to start the development.

To leverage this feature in OpenAPI 3.0 specification, you need to define an example in each endpoint or operation. There are two different formats to support single example or multiple examples.

Here are several example endpoints as part of the OpenAPI 3.0 petstore specification

The following response defines a single example that returns an array of maps.

      responses:
        '200':
          description: An paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
              example:
                - id: 1
                  name: catten
                  tag: cat
                - id: 2
                  name: doggy
                  tag: dog

The following response defines a single example that returns a map.

      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
              example:
                id: 1
                name: Jessica Right
                tag: pet

The following response defines multiple examples, and the generator picks up the first entry to return a map.

      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
              examples:
                response:
                  value:
                    id: 1
                    name: Jessica Right
                    tag: pet

The light-codegen leverages the defined examples in the generated handler for endpoints. If you want to see the example output, please refer to petstore tutorial.

Given this feature is built into the light-codegen, it is highly recommended to utilize it for your API development. It increases productivity dramatically, especially in microservices applications.

The format of the Swagger 2.0 specification is different than OpenAPI 3.0 specification. If you are using Swagger 2.0, please refer to Swagger 2.0 Mock tutorial for details.