Deterministic ordering of elements for ApiView Swagger view

element-ordering.md

Element Ordering for ApiView Swagger view

This document will define a deterministic ordering of fields at every level of an OpenAPI v2 document. ApiView should transform an input document to conform to this ordering.

ref: OpenAPI v2 Specification

Top level

ref: Swagger Object

• swagger
• info
• host
• basePath
• x-ms-parameterized-host
• schemes
• consumes
• produces
• securityDefinitions
• security
• tags
• externalDocs
• paths (include x-ms-paths with with some marker)
• definitions
• parameters
• responses
• an other x- properties in alpha order

Note: retain OpenAPI structure — don’t nest swagger, info, … security within “General”

Paths Object

ref: Paths Object

• by path (key)
• any x- properties in alpha order

Note: Include entries of x-ms-paths, but we will want these to be marked in some way (TBD).

Q: Should paths be grouped by tag? By “operationGroup”? Not for now.

Path Item

ref: Path Item Object

• parameters
• get
• put
• post
• patch
• delete

Operation

ref: Operation Object

• summary
• description
• operationId
• deprecated
• x-ms-long-running-operation
• x-ms-pageable
• tags
• externalDocs
• consumes
• produces
• security
• parameters
• responses
• x-ms-examples
• an other x- properties in alpha order

Q: Do we show the parameters at the path level within each operation ? Not for now, but eventually yes.

Q: Do we show “inherited” global consumes, produces, security ? Not for now, but eventually yes.

Parameters

• maintain order in original document

Parameter Object

ref: Parameter Object

• name
• x-ms-client-name
• in
• description
• required
• default
• x-ms-client-default
• type
• format
• items
• collectionFormat
• enum
• x-ms-enum
• minimum/maximum/minLength/maxLength/pattern/etc
• an other x- properties in alpha order

Responses Object

• numbered status codes in sorted order
• default
• x-properties in alpha order

Response Object

ref: Response Object

• description
• headers
• schema
• examples

Schema Object

ref: Schema Object

• type

• format

• properties

• required

• allOf

• x-ms-client-name

• title

• description

• required

• default

• x-ms-client-default

• type

• format

• properties

• additionalProperties

• items

• collectionFormat

• enum

• x-ms-enum

• minimum/maximum/minLength/maxLength/pattern/etc

• an other x- properties in alpha order

Definitions, Parameters, Responses

In alpha order by name.

Would be nice if the definitions were sorted in a "topological" way (cluster "child" definitions underneath parents as best possible)

Also ... cluster all the polymorphic types together.

Sorting this - and all our languages' tokens from the current tokenizers - is a great start. It's certainly cheaper than Azure/azure-sdk-tools#5374 that Praveen and I had discussed as an alternative. That'd likely be more useful for most scenarios, but certainly more costly. I think we should start with all languages effectively doing what you did here. I opened Azure/azure-sdk-tools#676 about that a while ago.