Is your feature request related to a problem

Kind of. I've seen a number of issues like #1082, #723 where people don't know exactly how to specify examples for their OAS docs. I made #1106 to improve the docs a bit on this point, but it seems like it could be more intuitive at the API level as well.

The solution you would like

My proposal is to select the example as follows:

• Example provided explicitly: Use that value
• Elif default value provided but no example: Use the default value as the example (or leave it out of the example if the default is None)
• Required field: example must be set explicitly

Describe alternatives you've considered

Improving the docs could help, but I think the API for examples could be cleaner too which is a "deeper" issue.

Additional context

A lot of my models currently look like

class Item(BaseModel):
    name: str = Field('some-name', example='some-name')
    id: int = Field(0, example=0)
    # etc. etc.

This change would help model definitions to be more DRY.

I'd be happy to contribute a PR if maintainers are open to this change.