chore(api): clean up API spec

[sebastianliebscher]

SUMMARY

This PR makes use of the OpenAPI specs summary to display relevant information in the API doc overview. This way, you don't have to expand every API endpoint to see what it does, improving usability by a lot.

I mostly replaced description with summary where the text was small enough. In some places with more explanatory text, description has been split into description and summary.

If this PR is too big, I'm happy to split it up.

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

After:

Before:

TESTING INSTRUCTIONS

• Navigate to /swagger/v1 and have a look

ADDITIONAL INFORMATION

• Has associated issue:
• Required feature flags:
• Changes UI
• Includes DB Migration (follow approval process in SIP-59)
  • Migration is atomic, supports rollback & is backwards-compatible
  • Confirm DB migration upgrade and downgrade tested
  • Runtime estimates and downtime expectations provided
• Introduces new feature or API
• Removes existing feature or API

[codecov]

Codecov Report

Merging #24838 (2389eb0) into master (ba508a7) will increase coverage by 0.01%.
Report is 11 commits behind head on master.
The diff coverage is 85.98%.

❗ Current head 2389eb0 differs from pull request most recent head 36559e6. Consider uploading reports for the commit 36559e6 to get more accurate results

@@            Coverage Diff             @@
##           master   #24838      +/-   ##
==========================================
+ Coverage   68.98%   69.00%   +0.01%     
==========================================
  Files        1903     1903              
  Lines       74007    74085      +78     
  Branches     8193     8193              
==========================================
+ Hits        51052    51120      +68     
- Misses      20834    20844      +10     
  Partials     2121     2121              

Flag	Coverage Δ
hive	54.14% <54.00%> (-0.02%)	⬇️
mysql	79.21% <88.00%> (+0.02%)	⬆️
postgres	79.31% <88.46%> (+0.02%)	⬆️
presto	54.04% <54.00%> (-0.02%)	⬇️
python	83.37% <88.46%> (+0.01%)	⬆️
sqlite	77.89% <88.00%> (+0.02%)	⬆️
unit	55.00% <70.19%> (+0.05%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files Changed	Coverage Δ
...et-chart-deckgl/src/layers/Geojson/controlPanel.ts	50.00% <ø> (ø)
...egacy-preset-chart-deckgl/src/layers/Path/Path.jsx	0.00% <ø> (ø)
...reset-chart-deckgl/src/layers/Path/controlPanel.ts	50.00% <ø> (ø)
...preset-chart-deckgl/src/layers/Polygon/Polygon.jsx	0.00% <ø> (ø)
...et-chart-deckgl/src/layers/Polygon/controlPanel.ts	33.33% <ø> (ø)
...reset-chart-deckgl/src/utilities/Shared_DeckGL.jsx	86.48% <ø> (ø)
...c/filters/components/Select/SelectFilterPlugin.tsx	59.21% <ø> (-2.52%)	⬇️
superset-frontend/src/pages/Tags/index.tsx	0.00% <0.00%> (ø)
superset-frontend/src/views/CRUD/hooks.ts	52.38% <ø> (ø)
superset/advanced_data_type/api.py	100.00% <ø> (ø)
... and 57 more

... and 1 file with indirect coverage changes

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[john-bodley]

Thanks @sebastianliebscher for exposing the summary and cleaning up/standardizing the API documentation.

[villebro]

This is an amazing piece of cleanup, thanks so much @sebastianliebscher! ❤️