Skip to content

Prefer description when referring to an OAS document #1247

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jul 21, 2017
Merged

Prefer description when referring to an OAS document #1247

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ccf4651
Prefer `description` when referring to an OAS document
earth2marsh Jun 30, 2017
16e7257
Use `document` in place of `description` or `definition`
earth2marsh Jul 7, 2017
37ddaf2
Addressing comments
earth2marsh Jul 21, 2017
000e569
Fixing verb agreement, reverting one instance of document to definition
earth2marsh Jul 21, 2017
ad85d09
Merge branch 'OpenAPI.next' into earth2marsh-patch-1
earth2marsh Jul 21, 2017
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
30 changes: 14 additions & 16 deletions versions/3.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@ This document is licensed under [The Apache License, Version 2.0](http://www.apa

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools and many other use cases.
An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.

## Table of Contents
<!-- TOC depthFrom:1 depthTo:3 withLinks:1 updateOnSave:1 orderedList:0 -->

- [Definitions](#definitions)
- [OpenAPI Definition](#oasDefinition)
- [OpenAPI Document](#oasDocument)
- [Path Templating](#pathTemplating)
- [Media Types](#mediaTypes)
- [HTTP Status Codes](#httpCodes)
Expand Down Expand Up @@ -67,8 +67,8 @@ An OpenAPI definition can then be used by documentation generation tools to disp

## Definitions

##### <a name="oasDefinition"></a>OpenAPI Definition
A document or set of documents which defines an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.
##### <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="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 @@ -104,11 +104,11 @@ The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate th

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 definition compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 definition documents contain a top-level version field named [`swagger`](http://swagger.io/specification/#swaggerObject) and value `"2.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`](http://swagger.io/specification/#swaggerObject) and value `"2.0"`.)

### Format

An API description that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.

For example, if a field has an array value, the JSON array representation will be used:

Expand All @@ -128,22 +128,20 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA
- Tags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231).
- Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](http://yaml.org/spec/1.2/spec.html#id2802346).

**Note:** While APIs are described by OpenAPI documents in YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
**Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.

### <a name="documentStructure"></a>Document Structure

An OpenAPI definition MAY be made up of a single document.
However, parts of the definitions MAY be split into separate documents, at the discretion of the user.
This is applicable for `$ref` fields in the specification as follows from the [JSON Schema](http://json-schema.org) definitions.
An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, `$ref` fields MUST be used in the specification to reference those parts as follows from the [JSON Schema](http://json-schema.org) definitions.

It is RECOMMENDED that the root OpenAPI definition document be named: `openapi.json` or `openapi.yaml`.
It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`.

### <a name="dataTypes"></a>Data Types

Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2).
Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part.
`null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution).
Models are described using the [Schema Object](#schemaObject) which is an extended subset of JSON Schema Specification Wright Draft 00.
Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00.
Copy link

@DavidBiesack DavidBiesack Jul 10, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you mean to change this to documented? I think defined works well here 😄

Copy link
Member Author

@earth2marsh earth2marsh Jul 10, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also thought defined worked well here, since I was trying to use document to (mostly) refer to the actual document itself and to not completely purge description and definition. Interestingly, JSON Schema's landing page seems to prefer describe in these situation.


<a name="dataTypeFormat"></a>Primitives have an optional modifier property: `format`.
OAS uses several known formats to define in fine detail the data type being used.
Expand Down Expand Up @@ -184,13 +182,13 @@ In the following description, if a field is not explicitly **REQUIRED** or descr

#### <a name="oasObject"></a>OpenAPI Object

This is the root document object of the [OpenAPI definition](#oasDefinition).
This is the root document object of the [OpenAPI document](#oasDocument).

##### Fixed Fields

Field Name | Type | Description
---|:---:|---
<a name="oasVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](http://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI definition uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI definition. This is *not* related to the API [`info.version`](#infoVersion) string.
<a name="oasVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](http://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="oasInfo"></a>info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.
<a name="oasServers"></a>servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`.
<a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API.
Expand All @@ -215,7 +213,7 @@ Field Name | Type | Description
<a name="infoTermsOfService"></a>termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL.
<a name="infoContact"></a>contact | [Contact Object](#contactObject) | The contact information for the exposed API.
<a name="infoLicense"></a>license | [License Object](#licenseObject) | The license information for the exposed API.
<a name="infoVersion"></a>version | `string` | **REQUIRED**. The version of the API definition (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version).
<a name="infoVersion"></a>version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version).


This object MAY be extended with [Specification Extensions](#specificationExtensions).
Expand Down Expand Up @@ -319,7 +317,7 @@ An object representing a Server.

Field Name | Type | Description
---|:---:|---
<a name="serverUrl"></a>url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI definition is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`.
<a name="serverUrl"></a>url | `string` | **REQUIRED**. A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`.
<a name="serverDescription"></a>description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
<a name="serverVariables"></a>variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value. The value is used for substitution in the server's URL template.

Expand Down