Add documentation for the HTTP connection (#15379)

Add documentation for the http connection so it is more clear to a new user how to set them up. This PR also links the new documentation to operators, hooks, and sensors that use a http connection.

airflow/providers/http/hooks/http.py

@@ -31,9 +31,9 @@ class HttpHook(BaseHook):
 
     :param method: the API method to be called
     :type method: str
-    :param http_conn_id: connection that has the base API url i.e https://www.google.com/
-        and optional authentication credentials. Default headers can also be specified in
-        the Extra field in json format.
+    :param http_conn_id: :ref:`http connection<howto/connection:http>` that has the base
+        API url i.e https://www.google.com/ and optional authentication credentials. Default
+        headers can also be specified in the Extra field in json format.
     :type http_conn_id: str
     :param auth_type: The auth type for the service
     :type auth_type: AuthBase of python requests lib

airflow/providers/http/operators/http.py

@@ -31,7 +31,8 @@ class SimpleHttpOperator(BaseOperator):
         For more information on how to use this operator, take a look at the guide:
         :ref:`howto/operator:SimpleHttpOperator`
 
-    :param http_conn_id: The connection to run the operator against
+    :param http_conn_id: The :ref:`http connection<howto/connection:http>` to run
+        the operator against
     :type http_conn_id: str
     :param endpoint: The relative part of the full url. (templated)
     :type endpoint: str

airflow/providers/http/sensors/http.py

@@ -50,7 +50,8 @@ def response_check(response, task_instance):
         For more information on how to use this operator, take a look at the guide:
         :ref:`howto/operator:HttpSensor`
 
-    :param http_conn_id: The connection to run the sensor against
+    :param http_conn_id: The :ref:`http connection<howto/connection:http>` to run the
+        sensor against
     :type http_conn_id: str
     :param method: The HTTP request method to use
     :type method: str

docs/apache-airflow-providers-http/connections/http.rst

@@ -0,0 +1,68 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+
+
+.. _howto/connection:http:
+
+HTTP Connection
+===============
+
+The HTTP connection enables connections to HTTP services.
+
+Authenticating with HTTP
+------------------------
+
+Login and Password authentication can be used along with any authentication method using headers.
+Headers can be given in json format in the Extras field.
+
+Default Connection IDs
+----------------------
+
+The HTTP operators and hooks use ``http_default`` by default.
+
+Configuring the Connection
+--------------------------
+
+Login (optional)
+    Specify the login for the http service you would like to connect too.
+
+Password (optional)
+    Specify the password for the http service you would like to connect too.
+
+Host (optional)
+    Specify the entire url or the base of the url for the service.
+
+Port (optional)
+    Specify a port number if applicable.
+
+Schema (optional)
+    Specify the service type etc: http/https.
+
+Extras (optional)
+    Specify headers in json format.
+
+When specifying the connection in environment variable you should specify
+it using URI syntax.
+
+Note that all components of the URI should be URL-encoded.
+
+For example:
+
+.. code-block:: bash
+
+   export AIRFLOW_CONN_HTTP_DEFAULT='http://username:password@servvice.com:80/https?headers=header'

docs/apache-airflow-providers-http/index.rst

@@ -26,6 +26,7 @@ Content
     :maxdepth: 1
     :caption: Guides
 
+    Connection types <connections/http>
     Operators <operators>
 
 .. toctree::