5

I'm trying to define a POST method on a user class in the online Swagger editor.

I want to be able to specify multiple fields in the request body and I would like the generated documentation to reflect that only 2 fields are required, the others are optional.

What do I have to do/change to make that so?

I have tried various variations with the "required" key word (see picture below for one), but haven't been able to make that work, it doesn't show in the generated documentation (see picture below right side with my annotations in red).

Here is my POST definition in the editor:

enter image description here

Here is the generated documenation preview where I have indicated the things I should like to see changed.

enter image description here

PS. There are some more (olders) posts addressing this, but I really don't think this is a duplicate.

Ytsen de Boer
  • 2,797
  • 2
  • 25
  • 36
  • 1
    Does this answer your question? [How to specify if a field is optional or required in swagger?](https://stackoverflow.com/questions/40113049/how-to-specify-if-a-field-is-optional-or-required-in-swagger) – Helen Sep 17 '20 at 18:10
  • 1
    Your 2nd example is correct. Switch to the "Schema" tab to see the schema documentation, that's where the field descriptions (including the required flag) are displayed. – Helen Sep 17 '20 at 18:12
  • Youvegottobekiddingme ... you are right! Now I'll have to figure out how to have that "schema" shown as default ... (a poropos, the other post did not help me because it is about fields in a model, not in a method, but it does make more sense to me now, though). – Ytsen de Boer Sep 17 '20 at 18:14
  • Please [edit] your post to add code and data as text ([using code formatting](https://stackoverflow.com/editing-help#code)), not images. Images: A) don't allow us to copy-&-paste the code/errors/data for testing; B) don't permit searching based on the code/error/data contents; and [many more reasons](https://meta.stackoverflow.com/a/285557). Images should only be used, in addition to text in code format, if having the image adds something significant that is not conveyed by just the text code/error/data. See [mcve] on what code is required. – Adriaan Jul 25 '22 at 13:00

1 Answers1

8

I want to be able to specify multiple fields in the request body and I would like the generated documentation to reflect that only 2 fields are required, the others are optional.

Your second example is correct. To specify the required object properties, add required: [prop1, prop2, ...] on the object level (i.e. alongside type: object). Properties not listed in the required list are optional. If the required list is not provided, all properties are optional.

type: object
required: [email, password]  # <--------
properties:
  email:
    type: string
  password:
    type: string
  name:
    type: string

In Swagger UI, operation-specific schema documentation is displayed on the Schema (or Model) tab. That's where the property descriptions, data types, "required" indicators, and other schema info is displayed.

enter image description here

Now I'll have to figure out how to have that "schema" shown as default

To make the Schema/Model tab active by default, configure Swagger UI with the defaultModelRendering option set to "model".

Helen
  • 87,344
  • 17
  • 243
  • 314
  • how to achieve this within a ```C#``` project source code? i have a request body object that swaggers automatically reads and parses, and i want to make the ```From``` field optional: ``` public class EmailRequest { public EmailAddress From { get; set; } ... ``` – ulkas Sep 13 '22 at 09:34
  • @ulkas please [ask a new question](https://stackoverflow.com/questions/ask?tags=c%23+openapi) – Helen Sep 13 '22 at 09:41