CODEWITHSUNDEEP
swaggeropenapi
RAbraham
RAbraham

Reputation: 6306

OpenAPI: mix of mandatory fields, optional fields and unspecified fields

I need to specify that my endpoint has a mandatory field, an optional field and open to any number of fields(which can be sent without validation).

For e.g. for an endpoint /user 

user_id: str, mandatory
timestamp_utc: timestamp, optional
..*accept_any_extra_fields**..

So if someone sends the following json to my endpoint, the endpoint should accept it 

{ "user_id": 1,
  "name": "Sam",
  "location": "USA"
}

but it fails if the following json is sent as it does not contain user_id.

{ "name": "Sam",
  "location": "USA"
}

it should fail.

I'm new to OpenAPI/Swagger. I know I can send the extra data. But how do I describe this as documentation on OpenAPI so a person(or a program) knows that they can send any field (e.g. name, location) along with user_id

Upvotes: 5

Views: 7946

Answers (2)

Helen
Helen

Reputation: 97540

The additionalProperties keyword allows a schema to have extra properties besides those listed in the properties section.

MyModel:
  type: object
  required:
    - user_id
  properties:
    user_id:
      type: string
    timestamp_utc:
      type: string
  additionalProperties: true   # OpenAPI 3.x
  # or
  # additionalProperties: {}   # OpenAPI 2.0

Actually OpenAPI schemas are open to extension by default, in the absence of the additionalProperties keyword. However, some tools consider the absence of additionalProperties as "additional properties NOT allowed", so it's best to add additionalProperties: true / additionalProperties: {} explicitly just in case.

If the extra properties are limited to a specific data type, e.g. string, use

 additionalProperties:
   type: string

Upvotes: 4

Marcos Echagüe
Marcos Echagüe

Reputation: 597

Do you use Java-Spring? I use Swagger in Annotation approach in my Spring controllers, and in java code, you can specify params that you need in this way:

@ApiOperation(value = "Get user", notes = "Get a user by the given filters")
@GetMapping("v1/users")
public UserDTO getUsers(@ApiParam(value = "User id", required = true)
                        @RequestParam(value = "user_id", required = true) String userId,

                        @ApiParam(value = "Date", required = false)
                        @RequestParam(value = "timestamp_utc", required = false) 
                        @DateTimeFormat(iso = DateTimeFormat.ISO.DATE_TIME) LocalDateTime utc,

                        @ApiParam(value = "Some other", required = false)
                        @RequestParam(value = "some_other", required = false) String someOther){

             return service.getUser(userId, utc, someOther);
      }

The annotation @ApiOperation is to describre your endpint.

The annotation @ApiParam is to describe the param characteristics, and the attribute required is to inform that is.

Don't forget to add the swagger dependencies, here is on maven.

You also have the possibility to generate your API documentation in YAML. An example is here . Please check the endpoint for user/login.

I hope my answer will help you.

Upvotes: 2

Related Questions