Explain how to add Swagger REST API doc coverage in zulip.yaml.

Introduce Swagger UI and the Swagger/OpenAPI specification. Explain
the structure of zulip.yaml and show examples of different sections
of the file.

This is a new file in /docs not yet included in the Read the Docs
table of contents. Where it should go should be determined as we iterate
on the Swagger UI integration and expand REST API doc coverage using it.

For more on Swagger UI and how Zulip uses it, see:
https://github.com/zulip/zulip/issues/3474
https://github.com/zulip/zulip/pull/3397

With some minor tweaks to advertise this by tabbott.

docs/index.rst

@@ -139,5 +139,6 @@ Contents:
    logging
    release-checklist
    api-release-checklist
+   swagger-api-docs
    README
    user-docs

docs/swagger-api-docs.md

@@ -0,0 +1,192 @@
+# Swagger API documentation
+
+The [Swagger](http://swagger.io/specification/) (or OpenAPI)
+specification is a standardized way to describe how an API
+functions. This description then can then be used by any tool that
+supports the standard.
+
+Zulip uses the Swagger spec to generate an API reference from the
+`zulip.yaml` file. This page is a basic introduction to the format of
+this file and how to add content to it.
+
+In a Swagger file, every configuration section is an object. Objects
+may contain other objects, or reference objects defined
+elsewhere. Larger API specifications may be split into multiple
+files. There are more types of objects than mentioned here, you can
+find the complete details at
+[Swagger/OpenAPI specification page](http://swagger.io/specification).
+
+This library isn't in production use yet, but it is our current plan
+for how Zulip's API documentation will work.
+
+## Working with the `zulip.yaml` file
+
+A Swagger specification file has three general parts: information and
+configuration, endpoint definitions, and object schemas referenced by
+other objects (as an alternative to defining everything inline.)
+References can either specify an individual object, using `$ref:`, or
+compose a larger definition from individual objects with `allOf:`
+(which may itself contain a `$ref`.)
+
+### Configuration
+
+These objects, at the top of `zulip.yaml`, identify the API, define
+the backend host for the working examples, list supported schemes and
+types of authentication, and configure other settings. Once defined,
+information in this section rarely changes.
+
+For example, the `swagger` and `info` objects look like this:
+```
+# Basic Swagger UI info
+swagger: '2.0'
+info:
+  version: '1.0.0'
+  title: Zulip REST API
+  description: Powerful open source group chat
+  contact:
+    url: https://zulip.org/
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+```
+
+### Endpoint definitions
+
+The [Paths Object](http://swagger.io/specification/#pathsObject)
+contains
+[Path Item Objects](http://swagger.io/specification/#pathItemObject)
+for each endpoint. It describes in detail the methods and parameters
+the endpoint accepts and responses it returns.
+
+There is one Path Item Object for each supported method, containing a
+[Parameters Definition Object](http://swagger.io/specification/#parametersDefinitionObject)
+describing the required and optional inputs. A
+[Response Object](http://swagger.io/specification/#responseObject)
+similarly specifies the content of the response. They may reference
+schemas from a global Definitions Object (see [Schemas](#schemas),
+below.)
+
+Example:
+
+The `/users/{user}/presence` endpoint (defined in a
+[Path Item Object](http://swagger.io/specification/#pathItemObject))
+expects a GET request with one
+[parameter](http://swagger.io/specification/#parameterObject), HTTP
+Basic authentication, and returns a JSON response containing `msg`,
+`result`, and `presence` values.
+
+```
+/users/{user}/presence:
+  get:
+    description: Get presence data for another user.
+    operationId: getPresence
+    parameters:
+    - name: user
+      in: path
+      description: Enter email address
+      required: true
+      type: string
+    security:
+    - basicAuth: []
+    responses:
+      '200':
+        description: The response from a successful call
+        schema:
+          type: object
+          required:
+          - msg
+          - result
+          - presence
+          properties:
+            msg:
+              type: string
+            result:
+              type: string
+            presence:
+              type: array
+```
+
+### Schemas
+
+The
+[Definitions Object](http://swagger.io/specification/#definitionsObject)
+contains schemas referenced by other objects. For example,
+`MessageResponse`, the response from the `/messages` endpoint,
+contains three required parameters.  Two are strings, and one is an
+integer.
+
+```
+MessageResponse:
+  type: object
+  required:
+    - msg
+    - result
+    - id
+  properties:
+    msg:
+      type: string
+    result:
+      type: string
+    id:
+      type: integer
+      format: int64
+```
+
+You can find more examples, including GET requests and nested objects, in
+`/static/yaml/zulip.yaml`.
+
+## Zulip Swagger YAML style:
+
+We're collecting decisions we've made on how our Swagger YAML files
+should be organized here:
+
+* Use shared definitions and YAML anchors to avoid duplicating content
+  where possible.
+
+## Tips for working with YAML:
+
+You can edit YAML files in any text editor. Indentation defines
+blocks, so whitespace is important (as it is in Python.) TAB
+characters are not permitted.  If your editor has an option to replace
+tabs with spaces, this is helpful.
+
+You can also use the
+[Swagger Editor](http://swagger.io/swagger-editor), which validates
+YAML and understands the Swagger specification. Download and run it
+locally, or use the online version. If you aren't using a YAML-aware
+editor, make small changes and check your additions often.
+
+Note: if you are working with
+[Swagger UI](http://swagger.io/swagger-ui/) in a local development
+environment, it uses an online validator that must be able to access
+your file. You may see a red "ERROR" button at the bottom of your API
+docs page instead of the green "VALID" one even if your file is
+correct.
+
+### Formatting help:
+
+* Comments begin with a # character.
+
+* Descriptions do not need to be in quotes, and may use common
+  Markdown format options like inline code \` (backtick) and `#`
+  headings.
+
+* A single `|` (pipe) character begins a multi-line description on the
+  next line.  Single spaced lines (one newline at the end of each) are
+  joined. Use an extra blank line for a paragraph break.
+
+### Examples:
+
+```
+Description: This is a single line description.
+```
+
+```
+Description: |
+             This description has multiple lines.
+             Sometimes descriptions can go on for
+             several sentences.
+
+             A description might have multiple paragraphs
+             as well.
+```

static/swagger/zulip.yaml

@@ -2,7 +2,11 @@
 # for the Zulip REST API.
 #
 # For details on the Swagger/OpenAPI specification, see http://swagger.io/specification
-
+#
+# Our own documentation lives at
+#
+#   https://zulip.readthedocs.io/en/latest/swagger-api-docs.html
+#
 # Basic Swagger UI info
 swagger: '2.0'
 info: