- Swagger 2.0 Specification
- Swagger Api Spec
- Openapi Description Markdown Function
- Openapi Description Markdown Key
These options may be applied as additional-properties (cli) or configOptions (plugins). Refer to configuration docs for more details.
Option | Description | Values | Default |
---|---|---|---|
allowUnicodeIdentifiers | boolean, toggles whether unicode identifiers are allowed in names or not, default is false | false | |
disallowAdditionalPropertiesIfNotPresent | If false, the 'additionalProperties' implementation (set to true by default) is compliant with the OAS and JSON schema specifications. If true (default), keep the old (incorrect) behaviour that 'additionalProperties' is set to false by default. |
| true |
ensureUniqueParams | Whether to ensure parameter names are unique in an operation (rename parameters that are not). | true | |
legacyDiscriminatorBehavior | Set to false for generators with better support for discriminators. (Python, Java, Go, PowerShell, C#have this enabled by default). |
| true |
prependFormOrBodyParameters | Add form or body parameters to the beginning of the parameter list. | false | |
sortModelPropertiesByRequiredFlag | Sort model properties to place required parameters before optional parameters. | true | |
sortParamsByRequiredFlag | Sort method arguments to place required parameters before optional parameters. | true |
#IMPORT MAPPING
Type/Alias | Imports |
---|
OpenAPI can be intimidating when viewed as a single file. If you view an OpenAPI file that was generated by a code annotation tool, they are often optimizing each line break and stuff the entire definition into a single line. This is not usable by a human. Even when 'pretty printed' the output can be many thousands of lines and daunting to edit. Variable description is optional, but useful to have and supports Markdown for rich text formatting. Common use cases for server templating: Specifying multiple protocols (such as HTTP vs HTTPS). SaaS (hosted) applications where each customer has their own subdomain. Description: the description of your API, in OpenAPI and the automatic API docs UIs. Version: the version of your API, e.g. Useful for example if you had a previous version of the application, also using OpenAPI. To set them, use the parameters title, description, and version.
#INSTANTIATION TYPES
Type/Alias | Instantiated By |
---|
#LANGUAGE PRIMITIVES
#RESERVED WORDS
#FEATURE SET
#Client Modification Feature
Name | Supported | Defined By |
---|---|---|
BasePath | ✗ | ToolingExtension |
Authorizations | ✗ | ToolingExtension |
UserAgent | ✗ | ToolingExtension |
MockServer | ✗ | ToolingExtension |
#Data Type Feature
Name | Supported | Defined By |
---|---|---|
Custom | ✗ | OAS2,OAS3 |
Int32 | ✓ | OAS2,OAS3 |
Int64 | ✓ | OAS2,OAS3 |
Float | ✓ | OAS2,OAS3 |
Double | ✓ | OAS2,OAS3 |
Decimal | ✓ | ToolingExtension |
String | ✓ | OAS2,OAS3 |
Byte | ✓ | OAS2,OAS3 |
Binary | ✓ | OAS2,OAS3 |
Boolean | ✓ | OAS2,OAS3 |
Date | ✓ | OAS2,OAS3 |
DateTime | ✓ | OAS2,OAS3 |
Password | ✓ | OAS2,OAS3 |
File | ✓ | OAS2 |
Array | ✓ | OAS2,OAS3 |
Maps | ✓ | ToolingExtension |
CollectionFormat | ✓ | OAS2 |
CollectionFormatMulti | ✓ | OAS2 |
Enum | ✓ | OAS2,OAS3 |
ArrayOfEnum | ✓ | ToolingExtension |
ArrayOfModel | ✓ | ToolingExtension |
ArrayOfCollectionOfPrimitives | ✓ | ToolingExtension |
ArrayOfCollectionOfModel | ✓ | ToolingExtension |
ArrayOfCollectionOfEnum | ✓ | ToolingExtension |
MapOfEnum | ✓ | ToolingExtension |
MapOfModel | ✓ | ToolingExtension |
MapOfCollectionOfPrimitives | ✓ | ToolingExtension |
MapOfCollectionOfModel | ✓ | ToolingExtension |
MapOfCollectionOfEnum | ✓ | ToolingExtension |
#Documentation Feature
Name | Supported | Defined By |
---|---|---|
Readme | ✗ | ToolingExtension |
Model | ✓ | ToolingExtension |
Api | ✓ | ToolingExtension |
#Global Feature
Name | Supported | Defined By |
---|---|---|
Host | ✓ | OAS2,OAS3 |
BasePath | ✓ | OAS2,OAS3 |
Info | ✓ | OAS2,OAS3 |
Schemes | ✗ | OAS2,OAS3 |
PartialSchemes | ✓ | OAS2,OAS3 |
Consumes | ✓ | OAS2 |
Produces | ✓ | OAS2 |
ExternalDocumentation | ✓ | OAS2,OAS3 |
Examples | ✓ | OAS2,OAS3 |
XMLStructureDefinitions | ✗ | OAS2,OAS3 |
MultiServer | ✗ | OAS3 |
ParameterizedServer | ✗ | OAS3 |
ParameterStyling | ✗ | OAS3 |
Callbacks | ✓ | OAS3 |
LinkObjects | ✗ | OAS3 |
#Parameter Feature
Name | Supported | Defined By |
---|---|---|
Path | ✓ | OAS2,OAS3 |
Query | ✓ | OAS2,OAS3 |
Header | ✓ | OAS2,OAS3 |
Body | ✓ | OAS2 |
FormUnencoded | ✓ | OAS2 |
FormMultipart | ✓ | OAS2 |
Cookie | ✓ | OAS3 |
#Schema Support Feature
Name | Supported | Defined By |
---|---|---|
Simple | ✓ | OAS2,OAS3 |
Composite | ✓ | OAS2,OAS3 |
Polymorphism | ✓ | OAS2,OAS3 |
Union | ✗ | OAS3 |
#Security Feature
Name | Supported | Defined By |
---|---|---|
BasicAuth | ✓ | OAS2,OAS3 |
ApiKey | ✓ | OAS2,OAS3 |
OpenIDConnect | ✗ | OAS3 |
BearerToken | ✓ | OAS3 |
OAuth2_Implicit | ✓ | OAS2,OAS3 |
OAuth2_Password | ✓ | OAS2,OAS3 |
OAuth2_ClientCredentials | ✓ | OAS2,OAS3 |
OAuth2_AuthorizationCode | ✓ | OAS2,OAS3 |
#Wire Format Feature
Name | Supported | Defined By |
---|---|---|
JSON | ✓ | OAS2,OAS3 |
XML | ✓ | OAS2,OAS3 |
PROTOBUF | ✗ | ToolingExtension |
Custom | ✗ | OAS2,OAS3 |
You can customize several metadata configurations in your FastAPI application.
Swagger 2.0 Specification
Title, description, and version¶
You can set the:
- Title: used as your API's title/name, in OpenAPI and the automatic API docs UIs.
- Description: the description of your API, in OpenAPI and the automatic API docs UIs.
- Version: the version of your API, e.g.
v2
or2.5.0
.- Useful for example if you had a previous version of the application, also using OpenAPI.
To set them, use the parameters
title
, description
, and version
:With this configuration, the automatic API docs would look like:
Metadata for tags¶
You can also add additional metadata for the different tags used to group your path operations with the parameter
openapi_tags
.It takes a list containing one dictionary for each tag.
Each dictionary can contain:
name
(required): astr
with the same tag name you use in thetags
parameter in your path operations andAPIRouter
s.description
: astr
with a short description for the tag. It can have Markdown and will be shown in the docs UI.externalDocs
: adict
describing external documentation with:description
: astr
with a short description for the external docs.url
(required): astr
with the URL for the external documentation.
Create metadata for tags¶
Let's try that in an example with tags for
users
and items
.Create metadata for your tags and pass it to the
openapi_tags
parameter:Notice that you can use Markdown inside of the descriptions, for example 'login' will be shown in bold (login) and 'fancy' will be shown in italics (fancy).
Tip
You don't have to add metadata for all the tags that you use.
Use your tags¶
Use the
tags
parameter with your path operations (and APIRouter
s) to assign them to different tags: Adobe premiere elements 18 tutorials.Info
Read more about tags in Path Operation Configuration.
Check the docs¶
Swagger Api Spec
Now, if you check the docs, they will show all the additional metadata:
Order of tags¶
The order of each tag metadata dictionary also defines the order shown in the docs UI.
For example, even though
users
would go after items
in alphabetical order, it is shown before them, because we added their metadata as the first dictionary in the list.OpenAPI URL¶
Ernest hemingway memoirs movie. By default, the OpenAPI schema is served at
/openapi.json
.But you can configure it with the parameter
openapi_url
.For example, to set it to be served at
/api/v1/openapi.json
:With a large community of enthusiasts and developers, Blender comes loaded with a vast array of extensions that you can turn on or off easily. Some existing extensions include: Generators for trees, terrain, ivy and clouds. Fracture Objects. 3D Printing Toolbox. Rigify meta-rigging system. Python scripts are a versatile way to extend Blender functionality. Most areas of Blender can be scripted, including animation, rendering, import and export, object creation and automating repetitive tasks. To interact with Blender, scripts can make use of the tightly integrated API. Extending Blender; Scripting & Security. Scripts in Blend-Files; Controlling Script Execution; Add-on Tutorial. Intended Audience; Documentation Links; What is an Add-on? Your First Add-on; Your Second Add-on; Conclusions. Blender scripting.
If you want to disable the OpenAPI schema completely you can set
openapi_url=None
, that will also disable the documentation user interfaces that use it.Docs URLs¶
You can configure the two documentation user interfaces included:
Openapi Description Markdown Function
- Swagger UI: served at
/docs
.- You can set its URL with the parameter
docs_url
. - You can disable it by setting
docs_url=None
.
- You can set its URL with the parameter
- ReDoc: served at
/redoc
.- You can set its URL with the parameter
redoc_url
. - You can disable it by setting
redoc_url=None
.
- You can set its URL with the parameter
Openapi Description Markdown Key
For example, to set Swagger UI to be served at
/documentation
and disable ReDoc: