OpenAPI Specification: Difference between revisions
(→info) |
(→paths) |
||
| Line 18: | Line 18: | ||
=<code>paths</code>= | =<code>paths</code>= | ||
Contains a map of [[#path|paths]]. | |||
==Path== | |||
Each path contains zero or one of these [[#Operation|operations]]: GET, POST, PUT, HEAD, DELETE, PATCH, OPTIONS, a list of [[#Parameter|Parameters]] and a map of vendor extensions. | Each path contains zero or one of these [[#Operation|operations]]: GET, POST, PUT, HEAD, DELETE, PATCH, OPTIONS, a list of [[#Parameter|Parameters]] and a map of vendor extensions. | ||
==<span id='Operations'></span>Operation== | ===<span id='Operations'></span>Operation=== | ||
{{External|[https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operationObject OpenAPI 2.0 Operation]}} | {{External|[https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operationObject OpenAPI 2.0 Operation]}} | ||
| Line 27: | Line 31: | ||
Also see: {{Internal|Amazon_API_Gateway_Concepts#Integration_and_Swagger_Operations|Amazon API Gateway Integration}} | Also see: {{Internal|Amazon_API_Gateway_Concepts#Integration_and_Swagger_Operations|Amazon API Gateway Integration}} | ||
===Tags=== | ====Tags==== | ||
{{External|[https://swagger.io/docs/specification/grouping-operations-with-tags/ Grouping Operations with Tags]}} | {{External|[https://swagger.io/docs/specification/grouping-operations-with-tags/ Grouping Operations with Tags]}} | ||
Revision as of 23:20, 28 March 2019
Internal
Overview
The document addresses both OpenAPI 2.0 and OpenAPI 3.0. The differences will be emphasized.
Swagger Java Model
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
Also see:
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
More:
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"]]