Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

What is the difference between global definitions section and components section?

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
like image 866
user3754482 Avatar asked Aug 20 '19 04:08

user3754482


People also ask

What are the three primary sections in a swagger specification?

Basic authentication. API key (as a header or query parameter) OAuth 2 common flows (implicit, password, application and access code)

How do you pass multiple parameters in swagger?

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):

What is @openapidefinition?

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.

How many servers can you add to an OpenAPI specification?

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.


1 Answers

I am not exactly sure whether definitions is for Swagger 2.0 and components and schemas 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 and components be used in the same YAML file of type swagger: '2.0' or should we stick to either definitions or components?

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.

like image 182
Helen Avatar answered Oct 15 '22 13:10

Helen