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

Question

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

Answer 1

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.

Answer 2

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.0
# 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