<commit_before># Swagger Checklist for Microsoft Azure #

*Version 0.1, 11-28-2016*
----------
Latest version: [https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/swagger-checklist.md](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/swagger-checklist.md)

Editors:</br>
"XXX", Microsoft</br>
"YYY", Microsoft</br>
"ZZZ", Microsoft


## Executive Summary ##

This document defines a Swagger checklist for Microsoft Azure, along with clarifications, refinements, interpretations and amplifications of the Swagger specification to promote interoperability and usability in tools and libraries.

## Status of this Checklist ##

This is a working draft.

## Feedback ##

If there are areas in this specification that could be clearer, or if errors or omissions are identified, Microsoft would like to be notified to provide the best possible checklist for authoring Swagger specifications.

Please direct feedback and kudos to [<EMAIL>](mailto:<EMAIL>).

## Table of Contents ##

[Introduction](#introduction)</br>
[Notational Conventions](#notational-conventions)</br>
[Naming - Swagger Checklist](#naming---swagger-checklist)</br>
[Operation Semantics - Swagger Checklist](#operation-semantics---swagger-checklist)</br>
[Operational - Swagger Checklist](#operation-semantics---swagger-checklist)</br>
[Documentation - Swagger Checklist](#documentation---swagger-checklist)</br>
[Appendix A: References](#appendix-a-references)</br>
[Appendix B: Acknowledgments](#appendix-b-acknowledgments)</br>
[Appendix C: Revision History](#appendix-c-revision-history)

## Introduction ##

This document defines a Swagger checklist for Microsoft Azure, along with clarifications, refinements, interpretations and amplifications of the Swagger specification to promote interoperability and usability in tools and libraries.

Each section addresses a dimension of Swagger authoring and its effectiveness for delivering the best Azure developer experiences through tools and libraries built using a Swagger specification.

## Notational Conventions ##
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119](http://www.ietf.org/rfc/rfc2119.txt).

Normative statements of the checklist are presented in the following manner:

&#x25a2; *Mnnnn*: checklist text here.

OR

&#x25a2; *Snnnn*: checklist text here.

Where "M" stands for 'MUST' or 'MUST NOT' requirement. "S" stands for 'SHOULD' or 'SHOULD NOT' requirement. And, "nnnn" is replaced by a number that is unique among all the requirements in the checklist, thereby "nnnn" becomes a unique requirement identifier.


## Naming - Swagger Checklist ##

&#x25a2; *M1000*: Plural names MUST only be used to represent collections.

&#x25a2; *M1001*: List operations MUST be prefixed with "List" and MUST not be named as "GetXXXX" operations.

&#x25a2; *M1002*: Terminology in Swagger and Azure Portal MUST be the same.



## Operation Semantics - Swagger Checklist ##

&#x25a2; *M2000*: A Swagger specification MUST be accompanied with a document that describes management scenarios that can be realized using operations described in the Swagger.

&#x25a2; *M2001*: Read only parameters MUST be labeled as read only in Swagger.

&#x25a2; *M2002*: Boolean parameters MUST be represented as boolean in Swagger. Boolean parameters MUST NOT be represented as strings. Similarly, this requirements applies to other primitive data types such as integer, float and double. These primitive data types MUST be represented using [Swagger primitive data types](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types).

&#x25a2; *M2003*: Long running operations MUST be modeled as [long running operations](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/creating-swagger.md#longrunning) in Swagger.

&#x25a2; *M2004*: Required parameters MUST be labeled as required in Swagger.

&#x25a2; *M2005*: A collection of references that are read only MUST be marked as read only in Swagger.

&#x25a2; *M2006*: Mutability of properties MUST be marked up using [`x-ms-mutability` extension](https://github.com/Azure/autorest/tree/master/docs/extensions#x-ms-mutability).

&#x25a2; *M2007*: Error definitions MUST be abstracted, modeled and reused instead of introducing a plethora of error definitions that look the same with different names.<commit_msg>added list names<commit_after># Swagger Checklist for Microsoft Azure #

*Version 0.1, 11-28-2016*
----------
Latest version: [https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/swagger-checklist.md](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/swagger-checklist.md)

Editors:</br>
"XXX", Microsoft</br>
"YYY", Microsoft</br>
"ZZZ", Microsoft


## Executive Summary ##

This document defines a Swagger checklist for Microsoft Azure, along with clarifications, refinements, interpretations and amplifications of the Swagger specification to promote interoperability and usability in tools and libraries.

## Status of this Checklist ##

This is a working draft.

## Feedback ##

If there are areas in this specification that could be clearer, or if errors or omissions are identified, Microsoft would like to be notified to provide the best possible checklist for authoring Swagger specifications.

Please direct feedback and kudos to [<EMAIL>](mailto:<EMAIL>).

## Table of Contents ##

[Introduction](#introduction)</br>
[Notational Conventions](#notational-conventions)</br>
[Naming - Swagger Checklist](#naming---swagger-checklist)</br>
[Operation Semantics - Swagger Checklist](#operation-semantics---swagger-checklist)</br>
[Operational - Swagger Checklist](#operation-semantics---swagger-checklist)</br>
[Documentation - Swagger Checklist](#documentation---swagger-checklist)</br>
[Appendix A: References](#appendix-a-references)</br>
[Appendix B: Acknowledgments](#appendix-b-acknowledgments)</br>
[Appendix C: Revision History](#appendix-c-revision-history)

## Introduction ##

This document defines a Swagger checklist for Microsoft Azure, along with clarifications, refinements, interpretations and amplifications of the Swagger specification to promote interoperability and usability in tools and libraries.

Each section addresses a dimension of Swagger authoring and its effectiveness for delivering the best Azure developer experiences through tools and libraries built using a Swagger specification.

## Notational Conventions ##
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119](http://www.ietf.org/rfc/rfc2119.txt).

Normative statements of the checklist are presented in the following manner:

&#x25a2; *Mnnnn*: checklist text here.

OR

&#x25a2; *Snnnn*: checklist text here.

Where "M" stands for 'MUST' or 'MUST NOT' requirement. "S" stands for 'SHOULD' or 'SHOULD NOT' requirement. And, "nnnn" is replaced by a number that is unique among all the requirements in the checklist, thereby "nnnn" becomes a unique requirement identifier.


## Naming - Swagger Checklist ##

&#x25a2; *M1000*: Plural names MUST only be used to represent collections.

&#x25a2; *M1001*: List operations MUST be prefixed with "List" and MUST not be named as "GetXXXX" operations.

&#x25a2; *M1002*: List operations MUST use consistent names and semantics. List operations MUST NOT use any other names.

- `List()` - lists all resources under a subscription.
- `ListByResourceGroup()` - list all resources in a resource group within a subscription.
- `ListByParent()` - where "Parent" is a context specific name. It lists all resource under a parent.

&#x25a2; *M1003*: Terminology in Swagger and Azure Portal MUST be the same.



## Operation Semantics - Swagger Checklist ##

&#x25a2; *M2000*: A Swagger specification MUST be accompanied with a document that describes management scenarios that can be realized using operations described in the Swagger.

&#x25a2; *M2001*: Read only parameters MUST be labeled as read only in Swagger.

&#x25a2; *M2002*: Boolean parameters MUST be represented as boolean in Swagger. Boolean parameters MUST NOT be represented as strings. Similarly, this requirements applies to other primitive data types such as integer, float and double. These primitive data types MUST be represented using [Swagger primitive data types](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#data-types).

&#x25a2; *M2003*: Long running operations MUST be modeled as [long running operations](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/creating-swagger.md#longrunning) in Swagger.

&#x25a2; *M2004*: Required parameters MUST be labeled as required in Swagger.

&#x25a2; *M2005*: A collection of references that are read only MUST be marked as read only in Swagger.

&#x25a2; *M2006*: Mutability of properties MUST be marked up using [`x-ms-mutability` extension](https://github.com/Azure/autorest/tree/master/docs/extensions#x-ms-mutability).

&#x25a2; *M2007*: Error definitions MUST be abstracted, modeled and reused instead of introducing a plethora of error definitions that look the same with different names.
{'fraction_non_alphanumeric': 0.10137658734393341, 'fraction_numerical': 0.02272969800448191, 'mean_word_length': 5.298387096774194, 'pattern_counts': {'":': 0, '<': 29, '<?xml version=': 0, '>': 29, 'https://': 10, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1766050', 'n_tokens_mistral': 2803, 'n_tokens_neox': 2508, 'n_words': 1032}