JSON Query Parameter

style and explode cover the most common serialization methods, but not all. For more complex scenarios (for example, a JSON-formatted object in the query string), you can use the content keyword and specify the media type that defines the serialization format. Or you can use schema to define the JSON object. For more information, please visit schema vs content.

In this tutorial, we are going to create a service with one endpoint that accepts a JSON object as a query parameter. The use case is provided by one of our contributors @Dasanko in this issue

To generate the example project, we need to create a specification file named openapi.yaml and a config.json for the light-codegen.

You can find these two files and a README.md in the model-config repository. The following is the specification.

openapi: 3.0.0

info:
  title: TestProject
  version: 1.0.0

servers:
  - url: 'https://localhost:8443/api'

paths:
  /testEndPoint:
    get:
      parameters:
        - in: query
          name: TestObject
          schema:
            $ref: '#/components/schemas/TestObject'
      responses:
        '200':
          description: History something something
          content:
            application/json:
              schema:
                type: string

components:
  schemas:
    TestObject:
      type: object
      properties:
        testProperty:
          type: string

To generate the project with light-codegen.

cd ~/networknt
rm -rf light-example-4j/rest/openapi/json-query-param
java -jar light-codegen/codegen-cli/target/codegen-cli.jar -f openapi -o light-example-4j/rest/openapi/json-query-param -m model-config/rest/openapi/json-query-param/openapi.yaml -c model-config/rest/openapi/json-query-param/config.json

If you don’t want to generate the project yourself, you can check the generated project in the light-example-4j

Now you can start the server in the light-example-4j folder.

cd ~/networknt/light-example-4j/rest/openapi/json-query-param
mvn clean install exec:exec

Once the server is up and running, you can issue the following commands from another terminal.

curl -k -X GET https://localhost:8443/api/testEndPoint?TestObject={testProperty=testing}
curl -k -X GET https://localhost:8443/api/testEndPoint?TestObject=testProperty,testing
curl -k -X GET https://localhost:8443/api/testEndPoint?testProperty=testing
curl -k -X GET https://localhost:8443/api/testEndPoint?TestObject[testProperty]=testing

All the above commands should pass the light-rest-4j OpenAPI validator without any error. As there is no business logic implemented in the example application, the response body is empty with a response code of 200.

If you are interested, you can add the business logic to get the input parameter and return something meaningful.