Skip to content

[ToC] Update to use internal anchors #928

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 1 commit into from
Feb 27, 2017
Merged

[ToC] Update to use internal anchors #928

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
45 changes: 24 additions & 21 deletions versions/3.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,18 +17,20 @@ Additional utilities can also take advantage of the resulting files, such as tes
## Table of Contents
<!-- TOC depthFrom:1 depthTo:3 withLinks:1 updateOnSave:1 orderedList:0 -->

- [Revision History](#revision-history)
- [Definitions](#definitions)
- [Path Templating](#pathTemplating)
- [Media Types](#mediaTypes)
- [HTTP Status Codes](#httpCodes)
- [Specification](#specification)
- [Format](#format)
- [File Structure](#file-structure)
- [Data Types](#data-types)
- [Relative References In Urls](#relativeReferences)
- [File Structure](#fileStructure)
- [Data Types](#dataTypes)
- [Relative References In Urls](#relativeReferences)
- [Schema](#schema)
- [OpenAPI Object](#openapi-object)
- [Info Object](#info-object)
- [Contact Object](#contact-object)
- [License Object](#license-object)
- [OpenAPI Object](#oasObject)
- [Info Object](#infoObject)
- [Contact Object](#contactObject)
- [License Object](#licenseObject)
- [Server Object](#server-object)
- [Components Object](#components-object)
- [Paths Object](#paths-object)
Expand Down Expand Up @@ -62,21 +64,11 @@ Additional utilities can also take advantage of the resulting files, such as tes
- [Security Requirement Object](#security-requirement-object)
- [Specification Extensions](#specification-extensions)
- [Security Filtering](#security-filtering)
- [Appendix A: Revision History](#revisionHistory)


<!-- /TOC -->

## Revision History

Version | Date | Notes
--- | --- | ---
3.0.0-rc0 | 2017-02-28 | Implementor's draft of the 3.0 specification
2.0 | 2015-12-31 | Donation of Swagger 2.0 to the Open API Initiative
2.0 | 2014-09-08 | Release of Swagger 2.0
1.2 | 2014-03-14 | Initial release of the formal document.
1.1 | 2012-08-22 | Release of Swagger 1.1
1.0 | 2011-08-10 | First release of the Swagger Specification

## Definitions

##### <a name="pathTemplating"></a>Path Templating
Expand Down Expand Up @@ -130,15 +122,15 @@ 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)

### File Structure
### <a name="fileStructure"></a>File Structure

The OAS representation of the API is made of a single file.
However, parts of the definitions can be split into separate files, 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.

By convention, the OpenAPI Specification (OAS) file is named `openapi.json` or `openapi.yaml`.

### Data Types
### <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 value.
Models are described using the [Schema Object](#schemaObject) which is an extended subset of JSON Schema Specification Wright Draft 00.
Expand Down Expand Up @@ -3550,3 +3542,14 @@ Two examples for 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 a finer control over what the viewer can see.

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

Version | Date | Notes
--- | --- | ---
3.0.0-rc0 | 2017-02-28 | Implementor's draft of the 3.0 specification
2.0 | 2015-12-31 | Donation of Swagger 2.0 to the Open API Initiative
2.0 | 2014-09-08 | Release of Swagger 2.0
1.2 | 2014-03-14 | Initial release of the formal document.
1.1 | 2012-08-22 | Release of Swagger 1.1
1.0 | 2011-08-10 | First release of the Swagger Specification