[AIRFLOW-3395] Add REST API endpoints to the docs

[xnuinside]

Make sure you have checked all steps below.

Jira

• My PR addresses the following Airflow Jira issues and references them in the PR title. For example, "[AIRFLOW-3395] My Airflow PR"
  • https://issues.apache.org/jira/browse/AIRFLOW-3395
  • In case you are fixing a typo in the documentation you can prepend your commit with [AIRFLOW-XXX], code changes always need a Jira issue.

Description

• Here are some details about my PR, including screenshots of any UI changes:

I don't see any task about start using swagger or something else, so I added temporary doc for informing about existed endpoints

I also try to use flask autodoc https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/#module-sphinxcontrib.autohttp.flask but has an issue relative to defining flask app, I believe need to do some refactor to use flask app, so I just used simple httpdomain sphinx.

Added info about REST API endpoints in doc
result doc preview:

if try to use autofunction, for example, will be problems such as:

''' File "/Users/jvolkova/.virtualenvs/airflow_tutorial/lib/python2.7/site-packages/airflow/www_rbac/api/experimental/endpoints.py", line 38, in
requires_authentication = airflow.api.api_auth.requires_authentication
AttributeError: 'NoneType' object has no attribute 'requires_authentication'
''' so need to refactor 'endpoints.py' to avoid those issues, but I don't want to do it right now, because as I remember we plan do something with REST API

Tests

• My PR adds the following unit tests OR does not need testing for this extremely good reason:

Commits

• My commits all reference Jira issues in their subject lines, and I have squashed multiple commits if they address the same issue. In addition, my commits follow the guidelines from "How to write a good git commit message":
  1. Subject is separated from body by a blank line
  2. Subject is limited to 50 characters (not including Jira issue reference)
  3. Subject does not end with a period
  4. Subject uses the imperative mood ("add", not "adding")
  5. Body wraps at 72 characters
  6. Body explains "what" and "why", not "how"

Documentation

• In case of new functionality, my PR adds documentation that describes how to use it.
  • When adding new operators/hooks/sensors, the autoclass documentation generation needs to be added.

Code Quality

• Passes flake8

[xnuinside]

@ashb, @kaxil, @feng-tao, please review

[Fokko]

Nice one @xnuinside Looks great. I've restarted the CI.

[Fokko]

Looks good. We could also consider adding Swagger support to the experimental endpoint: https://github.com/soerface/flask-restful-swagger-2.0

[xnuinside]

@Fokko, fixed . about https://github.com/soerface/flask-restful-swagger-2.0 I think we could talk about it as an adding new feature with a separate task (something told to me, what it is not quick to add and, at first, need to decide what we want use swagger)

[xnuinside]

@Fokko, two tests failed with strange errors, I believe it's not relative to PR )

[xnuinside]

@Fokko, tests fail with 'Attempting to fetch rat
rm: cannot remove '/tmp/lib/apache-rat-0.12.jar': No such file or directory
Our attempt to download rat locally to /tmp/lib/apache-rat-0.12.jar failed. Please install rat manually.
ERROR: InvocationError for command '/app/scripts/ci/6-check-license.sh' (exited with code 255)'

[Fokko]

@xnuinside Some weird stuff happening with the CI, I've restarted them. Let's see what happens.

[ron819]

@Fokko The lib https://github.com/soerface/flask-restful-swagger-2.0 isn't maintained.

Better use https://github.com/noirbizarre/flask-restplus ?

[codecov-io]

Codecov Report

Merging #4236 into master will increase coverage by 0.5%.
The diff coverage is n/a.

@@            Coverage Diff            @@
##           master    #4236     +/-   ##
=========================================
+ Coverage   77.31%   77.82%   +0.5%     
=========================================
  Files         201      201             
  Lines       16366    16366             
=========================================
+ Hits        12654    12737     +83     
+ Misses       3712     3629     -83

Impacted Files	Coverage Δ
airflow/models.py	92.28% <0%> (+0.04%)	⬆️
airflow/www/views.py	69.37% <0%> (+0.12%)	⬆️
airflow/hooks/dbapi_hook.py	83.06% <0%> (+1.61%)	⬆️
airflow/hooks/hive_hooks.py	75.26% <0%> (+1.84%)	⬆️
airflow/utils/sqlalchemy.py	78.57% <0%> (+5.71%)	⬆️
airflow/operators/mysql_to_hive.py	100% <0%> (+100%)	⬆️
airflow/operators/mysql_operator.py	100% <0%> (+100%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 930e2ff...99ee610. Read the comment docs.

[xnuinside]

@Fokko, yeeee ) successful Travis build

[Fokko]

@Fokko The lib https://github.com/soerface/flask-restful-swagger-2.0 isn't maintained.

Better use https://github.com/noirbizarre/flask-restplus ?

Good point, I'm not really into the different swagger extensions for Flask, so the flask-restful-swagger-2.0 was just a suggestion. flask-restplus sounds like a better alternative.

[Fokko]

Thanks @xnuinside :-)

[ashb]

Swagger is now rebranded and re-badged as OpenAPI (Sometimes also called Swagger v3) so it would be nice to find a module supporting that:

https://smartbear.com/blog/develop/what-is-the-difference-between-swagger-and-openapi/