<commit_before>Introduction to REST API Documentation
===============================

Introduction
-------------

DocFX now supports generating documentation from REST APIs following [Swagger specification](http://swagger.io/specification/) version 2.0.

The Swagger RESTful API files *MUST* end with `.json`.

One Swagger API file generates one HTML file. For example, a file `contacts.swagger.json` generates file naming `contacts.html`.

Basic structure
--------------
A single Swagger API file is considered as a unique REST **File** containing multiple **API**s. The **UID**(Unique IDentifier) for the **File** is defined as the combination of `host`, `basePath`, `info.title` and `info.version` with `/` as separator. For example, the following Swagger API file has **UID** equals to `microsoft.com/docfx/Contacts/1.6`:

```json
{
  "swagger": "2.0",
  "info": {
    "title": "Contacts",
    "version": "1.6"
  },
  "host": "microsoft.com",
  "basePath": "/docfx",
  "schemes": [
    "https"
  ]
}<commit_msg>Update intro_rest_api_documentation.md (#2012)<commit_after>Introduction to REST API Documentation
===============================

Introduction
-------------

DocFX supports generating documentation from REST APIs following [Swagger specification](http://swagger.io/specification/) version 2.0.

The Swagger RESTful API files *MUST* end with `.json`.

One Swagger API file generates one HTML file. For example, a file `contacts.swagger.json` generates file naming `contacts.html`.

Basic structure
--------------
A single Swagger API file is considered as a unique REST **File** containing multiple **API**s. The **UID**(Unique IDentifier) for the **File** is defined as the combination of `host`, `basePath`, `info.title` and `info.version` with `/` as separator. For example, the following Swagger API file has **UID** equals to `microsoft.com/docfx/Contacts/1.6`:

```json
{
  "swagger": "2.0",
  "info": {
    "title": "Contacts",
    "version": "1.6"
  },
  "host": "microsoft.com",
  "basePath": "/docfx",
  "schemes": [
    "https"
  ]
}
{'fraction_non_alphanumeric': 0.1843765162542455, 'fraction_numerical': 0.009704027171276079, 'mean_word_length': 4.017031630170316, 'pattern_counts': {'":': 14, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, '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': '2491365', 'n_tokens_mistral': 635, 'n_tokens_neox': 597, 'n_words': 217}