Skip to content

Commit 000a9a0

Browse files
fehguyfehguy
committed
moved it around, fixed example
1 parent 1dbcb29 commit 000a9a0

File tree

1 file changed

+72
-76
lines changed

1 file changed

+72
-76
lines changed

‎versions/3.0.md

Lines changed: 72 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ Field Name | Type | Description
127127
---|:---:|---
128128
<a name="oasVersion"></a>openapi | [OpenAPI Version String](#oasVersion) | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document.
129129
<a name="oasInfo"></a>info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed.
130-
<a name="oasHosts"></a>hosts | [Host Object](#hostObject) | An array of Host objects which provide connectivity information to a target host.
130+
<a name="oasHosts"></a>hosts | [Server Object](#serverObject) | An array of Server Objects which provide connectivity information to a target host.
131131
<a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API.
132132
<a name="oasComponents"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
133133
<a name="oasSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for the API as a whole. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition.
@@ -197,23 +197,80 @@ license:
197197
version: 1.0.1
198198
```
199199
200-
#### <a name="hostObject"></a>Host Object
200+
#### <a name="contactObject"></a>Contact Object
201201
202-
An object representing a Host.
202+
Contact information for the exposed API.
203203
204204
##### Fixed Fields
205205
206206
Field Name | Type | Description
207207
---|:---:|---
208-
<a name="hostUrlTemplate"></a>host URL template | `string` | A URL to the target host. This URL supports template variables and may be relative, to indicate that the host ___location is relative to the ___location where the OpenAPI Specification is being served. Templates are _optional_ and specified by the #hostTemplateParameter syntax. Template substitutions will be made when a variable is named in `{`brackets`}`.
208+
<a name="contactName"></a>name | `string` | The identifying name of the contact person/organization.
209+
<a name="contactUrl"></a>url | `string` | The URL pointing to the contact information. MUST be in the format of a URL.
210+
<a name="contactEmail"></a>email | `string` | The email address of the contact person/organization. MUST be in the format of an email address.
211+
212+
This object can be extended with [Specification Extensions](#specificationExtensions).
213+
214+
##### Contact Object Example:
215+
216+
```json
217+
{
218+
"name": "API Support",
219+
"url": "http://www.swagger.io/support",
220+
"email": "[email protected]"
221+
}
222+
```
223+
224+
```yaml
225+
name: API Support
226+
url: http://www.swagger.io/support
227+
email: [email protected]
228+
```
229+
230+
#### <a name="licenseObject"></a>License Object
231+
232+
License information for the exposed API.
233+
234+
##### Fixed Fields
235+
236+
Field Name | Type | Description
237+
---|:---:|---
238+
<a name="licenseName"></a>name | `string` | **Required.** The license name used for the API.
239+
<a name="licenseUrl"></a>url | `string` | A URL to the license used for the API. MUST be in the format of a URL.
240+
241+
This object can be extended with [Specification Extensions](#specificationExtensions).
242+
243+
##### License Object Example:
244+
245+
```json
246+
{
247+
"name": "Apache 2.0",
248+
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
249+
}
250+
```
251+
252+
```yaml
253+
name: Apache 2.0
254+
url: http://www.apache.org/licenses/LICENSE-2.0.html
255+
```
256+
257+
#### <a name="serverObject"></a>Server Object
258+
259+
An object representing a Server.
260+
261+
##### Fixed Fields
262+
263+
Field Name | Type | Description
264+
---|:---:|---
265+
<a name="serverUrlTemplate"></a>server URL template | `string` | A URL to the target host. This URL supports template variables and may be relative, to indicate that the host ___location is relative to the ___location where the OpenAPI Specification is being served. Templates are _optional_ and specified by the #hostTemplateParameter syntax. Template substitutions will be made when a variable is named in `{`brackets`}`.
209266
<a name="hostDescription"></a>host description | `string` | An optional string describing the host designated by the URL.
210267
<a name="hostTemplates"></a>templates | [Templates Object](#hostTemplatesObject) | An object holding templates for substitution in the URL template
211268

212269
This object can be extended with [Specification Extensions](#specificationExtensions).
213270

214-
##### Host Object Example
271+
##### Server Object Example
215272

216-
The following shows how multiple hosts can be described in the host object array
273+
The following shows how multiple hosts can be described in the Server Object array
217274

218275
```yaml
219276
servers:
@@ -225,28 +282,24 @@ servers:
225282
description: Production server
226283
```
227284

228-
The following shows how templates an be used for a host configuration
285+
The following shows how templates an be used for a server configuration
229286

230287
```yaml
231288
servers:
232-
- url: {scheme}://{host}:{port}/{basePath}
289+
- url: https://{username}.gigantic-server.com:{port}/{basePath}
233290
description: The production API server
234291
templates:
235-
scheme:
236-
enum:
237-
- https
238-
- http
239-
default: https
240-
host:
241-
enum:
242-
- na1.gigantic-server.com
243-
- na2.gigantic-server.com
292+
username:
293+
# note! no enum here means it is an open value
294+
default: demo
295+
description: this value is assigned by the service provider, in this example `gigantic-server.com`
244296
port:
245297
enum:
246298
- 8443
247299
- 443
248300
default: 8443
249301
basePath:
302+
# open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
250303
default: v2
251304
```
252305
@@ -268,68 +321,11 @@ An object representing a Host URL template
268321
Field Name | Type | Description
269322
---|:---:|---
270323
enum | [Possible Values] | An enumeration of primitive type values to be used if the substitution options are from a limited set.
271-
default | [Default Value] | **Required.** The default value to use for substitution if an alternate value is not specified
324+
default | [Default Value] | **Required.** The default value to use for substitution if an alternate value is not specified, and will be sent if an alternative value is _not_ supplied.
325+
description | `string` | An optional description for the template parameter
272326

273327
This object can be extended with [Specification Extensions](#specificationExtensions).
274328

275-
276-
#### <a name="contactObject"></a>Contact Object
277-
278-
Contact information for the exposed API.
279-
280-
##### Fixed Fields
281-
282-
Field Name | Type | Description
283-
---|:---:|---
284-
<a name="contactName"></a>name | `string` | The identifying name of the contact person/organization.
285-
<a name="contactUrl"></a>url | `string` | The URL pointing to the contact information. MUST be in the format of a URL.
286-
<a name="contactEmail"></a>email | `string` | The email address of the contact person/organization. MUST be in the format of an email address.
287-
288-
This object can be extended with [Specification Extensions](#specificationExtensions).
289-
290-
##### Contact Object Example:
291-
292-
```json
293-
{
294-
"name": "API Support",
295-
"url": "http://www.swagger.io/support",
296-
"email": "[email protected]"
297-
}
298-
```
299-
300-
```yaml
301-
name: API Support
302-
url: http://www.swagger.io/support
303-
email: [email protected]
304-
```
305-
306-
#### <a name="licenseObject"></a>License Object
307-
308-
License information for the exposed API.
309-
310-
##### Fixed Fields
311-
312-
Field Name | Type | Description
313-
---|:---:|---
314-
<a name="licenseName"></a>name | `string` | **Required.** The license name used for the API.
315-
<a name="licenseUrl"></a>url | `string` | A URL to the license used for the API. MUST be in the format of a URL.
316-
317-
This object can be extended with [Specification Extensions](#specificationExtensions).
318-
319-
##### License Object Example:
320-
321-
```json
322-
{
323-
"name": "Apache 2.0",
324-
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
325-
}
326-
```
327-
328-
```yaml
329-
name: Apache 2.0
330-
url: http://www.apache.org/licenses/LICENSE-2.0.html
331-
```
332-
333329
#### <a name="componentsObject"></a>Components Object
334330

335331
Holds a set of schemas for different aspects of the OAS.

0 commit comments

Comments
 (0)