✨ Add description parameter to all the security scheme classes, e.g. APIKeyQuery(name="key", description="A very cool API key")

[hylkepostma]

My suggestion is to add a description parameter to the __init__ methods of APIKeyQuery(SecurityBase):, APIKeyHeader(SecurityBase): and APIKeyCookie(SecurityBase): and use it to initialize the APIKey object. This allows for a description in the securitySchemes objects of the openapi.json and therefore in the Swagger and Redoc documentation.

class SecurityBase(BaseModel): already has an attribute description: Optional[str] = None.
class APIKey(SecurityBase): inherits from SecurityBase.

The classes APIKeyQuery(SecurityBase):, APIKeyHeader(SecurityBase): and APIKeyCookie(SecurityBase): initialize an APIKey object in their __init__ method. They initialize it with some kwargs and the name parameter, but currently without a description parameter.

Example: using APIKeyQuery(name="X-Auth-Key", auto_error=False, description="My description") would look likt this in Redoc:

[codecov]

Codecov Report

Merging #1757 (c55a195) into master (9121fcc) will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##            master     #1757    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files          390       401    +11     
  Lines         9747     10080   +333     
==========================================
+ Hits          9747     10080   +333     

Impacted Files	Coverage Δ
fastapi/security/api_key.py	100.00% <100.00%> (ø)
fastapi/security/http.py	100.00% <100.00%> (ø)
fastapi/security/oauth2.py	100.00% <100.00%> (ø)
fastapi/security/open_id_connect_url.py	100.00% <100.00%> (ø)
tests/test_security_api_key_cookie_description.py	100.00% <100.00%> (ø)
tests/test_security_api_key_header_description.py	100.00% <100.00%> (ø)
tests/test_security_api_key_query_description.py	100.00% <100.00%> (ø)
tests/test_security_http_base_description.py	100.00% <100.00%> (ø)
...ests/test_security_http_basic_realm_description.py	100.00% <100.00%> (ø)
tests/test_security_http_bearer_description.py	100.00% <100.00%> (ø)
... and 16 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 9121fcc...c55a195. Read the comment docs.

[github-actions]

📝 Docs preview for commit 466ddff at: https://5f32a7229003b29d44a1ebab--fastapi.netlify.app

[github-actions]

📝 Docs preview for commit c55a195 at: https://610282e611c6c0ad2ef9978a--fastapi.netlify.app

[tiangolo]

Thanks @hylkepostma! ☕

And thanks @nimctl for the review. 🤓

I updated it to include the description in all the security scheme classes and added tests for them all.

Thanks for your contribution! 🚀 🍰

This will be available later today in FastAPI version 0.68.0 🔖 🎉