Add OpenAPI spec

[mik-laj]

---

Issue link: WILL BE INSERTED BY boring-cyborg

Make sure to mark the boxes below before creating PR: [x]

• Description above provides context of the change
• Commit message/PR title starts with [AIRFLOW-NNNN]. AIRFLOW-NNNN = JIRA ID^*
• Unit tests coverage for changes (not needed for documentation changes)
• Commits follow "How to write a good git commit message"
• Relevant documentation is updated including usage instructions.
• I will engage committers as explained in Contribution Workflow Example.

^* For document-only changes commit message can start with [AIRFLOW-XXXX].

---

In case of fundamental code change, Airflow Improvement Proposal (AIP) is needed.
In case of a new dependency, check compliance with the ASF 3rd Party License Policy.
In case of backwards incompatible changes please leave a note in UPDATING.md.
Read the Pull Request Guidelines for more information.

[dlamblin]

If I may I'd like to recommend a diff with the following changes:
Spelling changes; referencing the correct object type; Summaries have less punctuation, descriptions have ending punctuation; Line-wrap to 100 chars; and optional TODO comments.
Also made all "Database entity fields" descriptions use capitalized nouns, but I'm uncertain about that part.

22,23c22
<   description: |
<     Apache Airflow management API
---
>   description: Apache Airflow management API.
35c34
<     description: Airfow Stable API
---
>     description: Airflow Stable API.
36a36
> # TODO: Generated docs and sandbox would like description for all paths
41c41
<       summary: Get all conneciton entries
---
>       summary: Get all connection entries
49c49
<           description: List of connection entry
---
>           description: List of connection entries.
62c62
<       summary: Create conneciton entry
---
>       summary: Create a connection entry
73c73
<           description: Successfull response
---
>           description: Successful response.
90c90
<       summary: Get connection entry
---
>       summary: Get a connection entry
95c95
<           description: Successfull response
---
>           description: Successful response.
122c122
<           description: Successfull response
---
>           description: Successful response.
137c137
<       summary: Delete connection entry
---
>       summary: Delete a connection entry
175,176c175,176
<       summary: Get basic information about DAG
<       description: Represent only information available at database (DAGModel).
---
>       summary: Get basic information about a DAG
>       description: Presents only information available in database (DAGModel).
181c181
<           description: Successfull response
---
>           description: Successful response.
199c199
<           description: Successfull response
---
>           description: Successful response.
210a211
>   # TODO: Can DAGs be triggered like /api/experimental/dags/<DAG_ID>/dag_runs (POST)?
217c218,219
<       description: This endpoint support reading resources across multiple DAGs by specify a "-" as a dag_id.
---
>       description: This endpoint supports reading resources across multiple DAGs by specifying
>         a "-" as a dag_id.
225c227
<           description: List of DAG Runs
---
>           description: List of DAG Runs.
241c243
<       summary: Get DAG Run
---
>       summary: Get a DAG Run
246c248
<           description: Successfull response
---
>           description: Successful response.
273c275
<           description: Successfull response
---
>           description: Successful response.
288c290
<       summary: Delete DAG Run
---
>       summary: Delete a DAG Run
293c295
<           description: No content
---
>           description: No content.
311c313
<           description: List of log entries
---
>           description: List of log entries.
335c337
<           description: Successfull response
---
>           description: Successful response.
352c354
<       summary: Get log entry
---
>       summary: Get a log entry
357c359
<           description: Successfull response
---
>           description: Successful response.
384c386
<           description: Successfull response
---
>           description: Successful response.
404c406
<           description: No content
---
>           description: No content.
422c424
<           description: List of import errors
---
>           description: List of import errors.
439c441
<       summary: Get import errors
---
>       summary: Get an import error
444c446
<           description: Successfull response
---
>           description: Successful response.
457c459
<       summary: Delete import error
---
>       summary: Delete an import error
462c464
<           description: No content
---
>           description: No content.
480c482
<           description: List of pools
---
>           description: List of pools.
493c495
<       summary: Create pool
---
>       summary: Create a pool
504c506
<           description: Successfull response
---
>           description: Successful response.
521c523
<       summary: Get pool
---
>       summary: Get a pool
526c528
<           description: Successfull response
---
>           description: Successful response.
540c542
<       operationId: upadtePool
---
>       operationId: updatePool
553c555
<           description: Successfull response
---
>           description: Successful response.
557c559
<                 $ref: '#/components/schemas/Connection'
---
>                 $ref: '#/components/schemas/Pool'
568c570
<       summary: Delete pool
---
>       summary: Delete a pool
573c575
<           description: No content
---
>           description: No content.
586,587c588,590
<       summary: Get list of task instance of DAG.
<       description: This endpoint support reading resources across multiple DAGs by specify a "-" as a dag_id.
---
>       summary: Get list of task instances of DAG
>       description: This endpoint support reading resources across multiple DAGs by specifying
>         a "-" as a dag_id.
595c598
<           description: List of task instances
---
>           description: List of task instances.
614c617
<       summary: Get task instance
---
>       summary: Get a task instance
619c622
<           description: Successfull response
---
>           description: Successful response.
647c650
<           description: Successfull response
---
>           description: Successful response.
667c670
<           description: No content
---
>           description: No content.
685c688
<           description: List of variables
---
>           description: List of variables.
698c701
<       summary: Create variables
---
>       summary: Create a variable
709c712
<           description: Successfull response
---
>           description: Successful response.
726c729
<       summary: Get variables
---
>       summary: Get a variable by id
728c731
<       description: The collection does not contain data. To get data, you must get a single entity
---
>       description: The collection does not contain data. To get data, you must get a single entity.
732c735
<           description: Successfull response
---
>           description: Successful response.
745c748
<       summary: Update a variable
---
>       summary: Update a variable by id
759c762
<           description: Successfull response
---
>           description: Successful response.
774c777
<       summary: Delete variable
---
>       summary: Delete a variable by id
779c782
<           description: No content
---
>           description: No content.
792c795
<       summary: Get variable using variable key.
---
>       summary: Get a variable by its key
798c801
<           description: Successfull response
---
>           description: Successful response.
819,820c822,823
<         This endpoint support reading resources across multiple Task Instance by specify a
<         "-" as a `dag_id`, `task_id` and `execution_date`.
---
>         This endpoint supports reading resources across multiple Task Instances by specifying
>         "-" as `dag_id`, `task_id` and `execution_date`.
828c831
<           description: List of XCom values
---
>           description: List of XCom values.
839a843
>     # TODO: Would be more consistent: post should add, patch with update_mask should update.
841c845
<       summary: Upddate the XCom entry
---
>       summary: Update XCom entries
852c856
<           description: Successfull response
---
>           description: Successful response.
872c876
<       summary: Get XCom entry
---
>       summary: Get an XCom entry
877c881
<           description: Successfull response
---
>           description: Successful response.
890c894
<       summary: Update a XCom entry
---
>       summary: Update an XCom entry
904c908
<           description: Successfull response
---
>           description: Successful response.
919c923
<       summary: Delete XCom entry
---
>       summary: Delete an XCom entry
924c928
<           description: No content
---
>           description: No content.
945c949
<           description: Successfull response
---
>           description: Successful response.
967c971
<       summary: Get logs for specific taskk instance
---
>       summary: Get logs for specific task instance
972c976
<           description: Content of logs
---
>           description: Content of logs.
999c1003
<       summary: Get simplified representation of DAG.
---
>       summary: Get simplified representation of DAG
1004c1008
<           description: Successfull response
---
>           description: Successful response.
1021c1025
<       summary: Get task for DAG
---
>       summary: Get tasks for a DAG
1026c1030
<           description: Successfull response
---
>           description: Successful response.
1044c1048
<       summary: Get simplified representation of Task.
---
>       summary: Get simplified representation of a task
1049c1053
<           description: Successfull response
---
>           description: Successful response.
1066c1070
<       summary: Get source code using file token.
---
>       summary: Get source code using file token
1071c1075
<           description: Successfull response
---
>           description: Successful response.
1088c1092
<       summary: Get current configuratiin
---
>       summary: Get current configuration
1096c1100
<           description: Return current configuration
---
>           description: Return current configuration.
1444a1449
>     # TODO: VariableCollectionItem already has a "value"
1693a1699
>         # TODO: Are we sure this shouldn't be microseconds instead?
1750c1756
<         [RFC7807](https://tools.ietf.org/html/rfc7807) compliant response
---
>         [RFC7807](https://tools.ietf.org/html/rfc7807) compliant response.
1756,1757c1762,1764
<             A URI reference [RFC3986] that identifies the problem type. This specification encourages that,
<             when dereferenced, it provide human-readable documentation for the problem type
---
>             A URI reference [RFC3986] that identifies the problem type. This specification
>             encourages that, when dereferenced, it provide human-readable documentation for
>             the problem type.
1760c1767
<           description: A short, human-readable summary of the problem  type.
---
>           description: A short, human-readable summary of the problem type.
1763c1770,1771
<           description: The HTTP status code generated by the API server for this occurrence of the problem.
---
>           description: The HTTP status code generated by the API server for this occurrence of
>             the problem.
1783a1792
>     # TODO: If these aren't generated there should at least be a lint-like test for synchronization
1834c1843
<       description: The number of items to skip before starting to collect the result set
---
>       description: The number of items to skip before starting to collect the result set.
1844c1853
<       description: The numbers of items to return
---
>       description: The numbers of items to return.
1853c1862
<       description: The connection ID
---
>       description: The Connection ID.
1861c1870
<       description: The DAG ID
---
>       description: The DAG ID.
1869c1878
<       description: The DAG Run ID
---
>       description: The DAG Run ID.
1877c1886
<       description: The Task ID
---
>       description: The Task ID.
1885c1894
<       description: The Task Try Number
---
>       description: The Task Try Number.
1893c1902
<       description: The Import Error ID
---
>       description: The Event Log ID.
1901c1910
<       description: The Import Error ID
---
>       description: The Import Error ID.
1909c1918
<       description: The Pool ID
---
>       description: The Pool ID.
1917c1926
<       description: The Variable ID
---
>       description: The Variable ID.
1925c1934
<       description: The Variable Key
---
>       description: The Variable Key.
1936,1937c1945,1946
<         [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6), for example,
<         `2017-07-21T17:32:28Z`
---
>         [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6),
>         E.G. `2017-07-21T17:32:28Z`.
1945c1954,1955
<       description: A full reply will be returned. By default, only the first fragment will be returned.
---
>       description: A full reply will be returned.
>         By default, only the first fragment will be returned.
1954,1955c1964,1966
<         A token that allows you to continue fetching logs. If passsed, it will specify the
<         location from which the download should be continued.
---
>         A token that allows you to continue fetching task logs.
>         If passed, it will specify the location from which the download should be continued.
> 
1962c1973
<       description: The XCom Key
---
>       description: The XCom Key.
1972,1974c1983,1985
<         The key containing the encrypted path to the file. Encryption and encryption takes place only on the
<         server side.  This prevents the client from reading an non-DAG file. This also ensures API
<         extensibility, because the format of encrypted data may change.
---
>         The key containing the encrypted path to the file. Encryption and decryption takes place
>         only on the server side. This prevents the client from reading an non-DAG file.
>         This also ensures API extensibility, because the format of encrypted data may change.
1983,1984c1994,1995
<         The fields to update on the connection. If absent or empty, all modifiable fields are updated.
<         A comma-separated list of fully qualified names of fields.
---
>         The fields to update on the object (connection, pool etc). If absent or empty, all
>         modifiable fields are updated. A comma-separated list of fully qualified names of fields.
2016c2027
<       description: A specified resource is not found,
---
>       description: A specified resource is not found.
2066c2077
<   url: http://airflow.apache.org
---
>   url: http://airflow.apache.org/docs/stable/api.html

[itayB]

Is it a typo? should Litn be Lint?

[gonzalezzfelipe]

I was just checking the specs and noticed this typo, I think you mean Create a pool.