Skip to content
This repository was archived by the owner on Jan 20, 2024. It is now read-only.

Adding fragments and libraries #4

Open
antoniogarrote wants to merge 3 commits into
base: oas4_raml2
Choose a base branch
from
Open

Adding fragments and libraries #4

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4ca9acb
Adding fragments
antoniogarrote Feb 13, 2018
b1facde
Adding libraries
antoniogarrote Feb 13, 2018
f7d9f97
fixing typos
antoniogarrote Feb 13, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
171 changes: 168 additions & 3 deletions versions/4.0.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# OpenAPI Specification

#### Version 3.0.1
#### Version 4.0.0

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://tools.ietf.org/html/bcp14) [RFC2119](https://tools.ietf.org/html/rfc2119) [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here.

Expand All @@ -17,10 +17,12 @@ An OpenAPI definition can then be used by documentation generation tools to disp

- [Definitions](#definitions)
- [OpenAPI Document](#oasDocument)
- [OpenAPI Fragment Document](#oasFragment)
- [OpenAPI Library Document](#oasLibrary)
- [Path Templating](#pathTemplating)
- [Media Types](#mediaTypes)
- [HTTP Status Codes](#httpCodes)
- [Specification](#specification)
- [OAS Document Specification](#specification)
- [Versions](#versions)
- [Format](#format)
- [Document Structure](#documentStructure)
Expand Down Expand Up @@ -58,8 +60,18 @@ An OpenAPI definition can then be used by documentation generation tools to disp
- [OAuth Flows Object](#oauthFlowsObject)
- [OAuth Flow Object](#oauthFlowObject)
- [Security Requirement Object](#securityRequirementObject)
- [Specification Extensions](#specificationExtensions)
- [Security Filtering](#securityFiltering)
- [OAS Fragment Document Specification](#fragment)
- [Versions](#fragmentVersions)
- [OAS Fragment Document Type](#fragmentDocumentType)
- [Schema](#fragmentSchema)
- [OpenAPI Fragment Object](#fragmentObject)
- [Fragment Components Object](#fragmentComponents)
- [OAS Library Document Specification](#library)
- [Versions](#libraryVersions)
- [OAS Library Document Type](#libraryDocumentType)
- [Schema](#librarySchema)
- [OpenAPI Fragment Object](#libraryObject)
- [Appendix A: Revision History](#revisionHistory)


Expand All @@ -70,6 +82,12 @@ An OpenAPI definition can then be used by documentation generation tools to disp
##### <a name="oasDocument"></a>OpenAPI Document
A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.

##### <a name="oasFragment"></a>OpenAPI Fragment Document
A document defines or describes a reusable OpenAPI component that can be referenced from multiple OpenAPI documents.

##### <a name="oasLibrary"></a>OpenAPI Library Document
A document defines or describes multiple reusable OpenAPI components that can be referenced from multiple OpenAPI documents.

##### <a name="pathTemplating"></a>Path Templating
Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters.

Expand Down Expand Up @@ -3364,6 +3382,153 @@ Two examples of this:
1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication.
2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different than hiding the path itself from the [Paths Object](#pathsObject), so the user will not be aware of its existence. This allows the documentation provider to finely control what the viewer can see.

## <a name="fragment"></a> OAS Fragment Document Specification

### <a name="fragmentVersions"></a>Versions

OAS Fragment documents, in the same way as the standard OAS documents, are versioned using [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification.

The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example.

Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`.

An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swaggerObject) and value `"2.0"`.)


### <a name="fragmentDocumentType"></a>OAS Fragment Document Type

OAS Fragment documents are identified using the required field ['openapi-document'](#oasDocumentType) with a value that must match the string `"OAS Fragment"`.

### <a name="fragmentSchema"></a>Schema

In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL.

#### <a name="fragmentObject"></a>OpenAPI Fragment Object

This is the root document object for a [OpenAPI Fragment Object](#fragmentObject)


##### Fixed Fields

Field Name | Type | Description
---|:---:|---
<a name="fragmentVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string
<a name="oasDocumentType"></a>openapi-document | `string` | **REQUIRED**. This string MUST be the [`OAS Fragment`] value identifying the fragment document
<a name="oasFragmentDescription"></a>description | string | Description of the fragment usage
<a name="fragmentComponents"></a>components | [Fragment Components Object](#fragmentComponentsObject) | An element to hold the schema for the fragment component

##### OpenAPI Fragment Object Example

A fragment for an schema can be described as:

``` yaml
openapi: 4.0.0
openapi-document: OAS Fragment
description: Schema fragment describing an account with code and balance
components:
schemas:
Account:
type: object
properties:
code:
type: string
balance:
type: number
```

#### <a name="fragmentComponents"></a>Fragment Components Object

OAS Fragment documents encode the information about a single component that can be re-used across multiple documents. The components object for a fragment is equivalent to the ['Components Object'](#componentsObject) of the main OAS Document but only one component can be encoded

##### Fixed Fields

Only one component key and value are allowed in OpenAPI Fragments

Field Name | Type | Description
---|:---|---
<a name="componentsSchemas"></a> schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject).
<a name="componentsResponses"></a> responses | Map[`string`, [Response Object](#responseObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Response Objects](#responseObject).
<a name="componentsParameters"></a> parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject).
<a name="componentsExamples"></a> examples | Map[`string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Example Objects](#exampleObject).
<a name="componentsRequestBodies"></a> requestBodies | Map[`string`, [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Request Body Objects](#requestBodyObject).
<a name="componentsHeaders"></a> headers | Map[`string`, [Header Object](#headerObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Header Objects](#headerObject).
<a name="componentsSecuritySchemes"></a> securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
<a name="componentsLinks"></a> links | Map[`string`, [Link Object](#linkObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Link Objects](#linkObject).
<a name="componentsCallbacks"></a> callbacks | Map[`string`, [Callback Object](#callbackObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Callback Objects](#callbackObject).

This object MAY be extended with [Specification Extensions](#specificationExtensions).

## <a name="fragment"></a> OAS Library Document Specification

### <a name="fragmentVersions"></a>Versions

OAS Library documents, in the same way as the standard OAS documents, are versioned using [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) (semver) and follows the semver specification.

The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate the OAS feature set. Typically, *`.patch`* versions address errors in this document, not the feature set. Tooling which supports OAS 3.0 SHOULD be compatible with all OAS 3.0.\* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between `3.0.0` and `3.0.1` for example.

Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version. Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`.

An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#swaggerObject) and value `"2.0"`.)


### <a name="fragmentDocumentType"></a>OAS Library Document Type

OAS Fragment documents are identified using the required field ['openapi-document'](#oasDocumentType) with a value that must match the string `"OAS Library"`.

### <a name="fragmentSchema"></a>Schema

In the following description, if a field is not explicitly **REQUIRED** or described with a MUST or SHALL, it can be considered OPTIONAL.

#### <a name="fragmentObject"></a>OpenAPI Library Object

This is the root document object for a [OpenAPI Library Object](#libraryObject)


##### Fixed Fields

Field Name | Type | Description
---|:---:|---
<a name="fragmentVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string
<a name="oasDocumentType"></a>openapi-document | `string` | **REQUIRED**. This string MUST be the [`OAS Library`] value identifying the library document
<a name="oasLibraryDescription"></a>description | string | Description of the library usage
<a name="Components"></a>components | [Fragment Components Object](#componentsObject) | An element to hold the schema for the library components

##### OpenAPI Library Object Example

A library with multiple components can be described as:

``` yaml
openapi: 4.0.0
openapi-document: OAS Fragment
description: Library with some shared components
components:
schemas:
User:
type: object
properties:
name:
type: string
age:
type: number
format: int32
Account:
type: object
properties:
code:
type: string
balance:
type: number
parameters:
freeTextSearch:
name: search
in: query
description: free text search value
required: false
schema:
type: string

```

## <a name="revisionHistory"></a>Appendix A: Revision History

Version | Date | Notes
Expand Down