OpenAPI Specification: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
Line 17: Line 17:
When imported in AWS API Gateway, the title provides the API [[Amazon_API_Gateway_Concepts#API_Name|name]].
When imported in AWS API Gateway, the title provides the API [[Amazon_API_Gateway_Concepts#API_Name|name]].


=<code>paths</code>=
=<tt>paths</tt>=


Contains a map of [[#path|paths]].
Contains a map of [[#path|paths]].

Revision as of 23:21, 28 March 2019

Internal

Overview

The document addresses both OpenAPI 2.0 and OpenAPI 3.0. The differences will be emphasized.

Swagger Java Model

SwaggerJavaModel.png

info

title

When imported in AWS API Gateway, the title provides the API name.

paths

Contains a map of paths.

Path

Each path contains zero or one of these operations: GET, POST, PUT, HEAD, DELETE, PATCH, OPTIONS, a list of Parameters and a map of vendor extensions.

Operation

OpenAPI 2.0 Operation

Also see:

Amazon API Gateway Integration

Tags

Grouping Operations with Tags
tags:
  -name: tag-a
   description: Something that would shed light on tag-a semantics
   externalDocs:
    url: http://example.com/my-docs/tag-a.html
   
paths:
  /a:
    get:
      tags:
        - tag-a
        - other-tag

Each API operation can be annotated with a list of tags. Tagged operations may be handled differently by tools and libraries. Optionally, each tag can get a "description" and an "externalDocs" in the global "tags" section on the root level. The tag names here should match those used in operations. The tag order in the global tags section also controls the default sorting in the UI - at least, for Swagger UI. It is possible to use a tag at operation level even if it is not specified on the root level.

Parameter

CORS

CORS in Swagger

More:

CORS

Organizatorium

x-nullable

Appears in automatically generated Swagger files, as such:

definitions:
    LibraryAccount:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          x-nullable: true
definitions:
  A:
    type: string
    title: A
    x-nullable: true

When used for an API Gateway import, it errors out as:

Unable to create model for 'LibraryAccount': Invalid model specified: Validation Result: warnings : [], errors : [Invalid model schema specified. Unsupported keyword(s): ["x-nullable"]]