docs: add password example to dataset import API

[villebro]

SUMMARY

Currently the import API schema isn't super explicit on the following:

1. why e.g. chart imports need a password map
2. In what format passwords should be provided.

This PR adds a more verbose description of the format of the password map to clarify how this should be done:

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

TESTING INSTRUCTIONS

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 #18580 (9d81053) into master (55cd7fb) will decrease coverage by 0.19%.
The diff coverage is n/a.

❗ Current head 9d81053 differs from pull request most recent head c9b6b47. Consider uploading reports for the commit c9b6b47 to get more accurate results

@@            Coverage Diff             @@
##           master   #18580      +/-   ##
==========================================
- Coverage   66.29%   66.09%   -0.20%     
==========================================
  Files        1594     1594              
  Lines       62623    62623              
  Branches     6312     6312              
==========================================
- Hits        41513    41393     -120     
- Misses      19459    19579     +120     
  Partials     1651     1651              

Flag	Coverage Δ
hive	?
mysql	81.24% <ø> (ø)
postgres	81.29% <ø> (ø)
presto	?
python	81.33% <ø> (-0.39%)	⬇️
sqlite	?

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

Impacted Files	Coverage Δ
superset/charts/api.py	85.93% <ø> (ø)
superset/dashboards/api.py	92.54% <ø> (ø)
superset/databases/api.py	93.99% <ø> (ø)
superset/datasets/api.py	91.89% <ø> (ø)
superset/queries/saved_queries/api.py	95.28% <ø> (ø)
superset/db_engines/hive.py	0.00% <0.00%> (-85.19%)	⬇️
superset/db_engine_specs/hive.py	70.27% <0.00%> (-15.45%)	⬇️
superset/db_engine_specs/presto.py	83.47% <0.00%> (-5.65%)	⬇️
superset/db_engine_specs/sqlite.py	91.89% <0.00%> (-5.41%)	⬇️
superset/connectors/sqla/utils.py	88.23% <0.00%> (-3.93%)	⬇️
... and 9 more

---

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 55cd7fb...c9b6b47. Read the comment docs.

[villebro]

@dpgaspar @betodealmeida - is there some reason we don't have a single consolidated /api/v1/import endpoint for importing zips containing any supported metadata? It seems that's what users would usually want to use.

[ad-m]

@dpgaspar @betodealmeida - is there some reason we don't have a single consolidated /api/v1/import endpoint for importing zips containing any supported metadata? It seems that's what users would usually want to use.

In this area it makes me wonder why is this nested object passed as a string instead of an object with additionalProperties: true?

[villebro]

In this area it makes me wonder why is this nested object passed as a string instead of an object with additionalProperties: true?

Good point @ad-m - However, to change this now would probably be considered a breaking change, so perhaps not something we want to do right now. But if we do introduce a new general import endpoint, maybe we could revisit this design question. So going to merge this to make the updated doc available.

[ad-m]

In this area it makes me wonder why is this nested object passed as a string instead of an object with additionalProperties: true?

Good point @ad-m - However, to change this now would probably be considered a breaking change

I believe we might express that as:

  "oneOf": [
   { "type": "string", "deprecated": true },
   { "type": "object", "additionalProperties": true }
  ]

to keep backward compatibility. As to the remainder, I agree that it may be worth taking this into account when implementing a new operation.