What is the difference between the global definitions
section and the components
section in Swagger 2.0?
I came across a Swagger definition YAML file which is marked as swagger: '2.0'
.
It has one section called definitions
just below parameters
. This is similar to what is described in
https://swagger.io/docs/specification/2-0/basic-structure/
under the "Input and Output Models" section.
Also further down the file, it has the components
section with the schemas
section underneath it. That is similar to what is described in
https://swagger.io/docs/specification/components/
This looks like OAS3.
However, this specific YAML file has both sections. I am not exactly sure whether definitions
is for Swagger 2.0 and components
and schemas
is in OAS 3.0. Is that so?
Can both definitions
and components
be used in the same YAML file of type swagger: '2.0'
or should we stick to either definitions
or components
?
# definitions section looks like this
definitions:
User:
properties:
id:
type: integer
name:
type: string
# Both properties are required
required:
- id
- name
# components section looks like this
components:
schemas:
Address:
type: object
properties:
line1:
type: string
city:
type: string
Basic authentication. API key (as a header or query parameter) OAuth 2 common flows (implicit, password, application and access code)
If you are trying to send a body with multiple parameters, add an object model in the definitions section and refer it in your body parameter, see below (works with editor.swagger.io):
The OpenAPI Specification is a standard format to define structure and syntax REST APIs. OpenAPI documents are both machine and human-readable, which enables anyone to easily determine how each API works. Engineers building APIs can use APIs to plan and design servers, generate code, and implement contract testing.
Multiple hosts are supported in OpenAPI 3.0. 2.0 supports only one host per API specification (or two if you count HTTP and HTTPS as different hosts). A possible way to target multiple hosts is to omit the host and schema from your specification and serve it from each host.
I am not exactly sure whether
definitions
is for Swagger 2.0 andcomponents
andschemas
is in OAS 3.0. Is that so?
Yes, exactly.
The definitions
section is used in OpenAPI 2.0 files (swagger: '2.0'
).
The components
section is used in OpenAPI 3.x (openapi: 3.x.x
).
Can both
definitions
andcomponents
be used in the same YAML file of typeswagger: '2.0'
or should we stick to eitherdefinitions
orcomponents
?
No, you can't mix 2.0 and 3.x syntax in the same file. If your file is swagger: '2.0'
you must use 2.0 syntax. If it's openapi: 3.0.0
you must use 3.0 syntax.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With