Order routes parameters by name in OpenAPI

[klaa97]

Currently, routes' parameters are listed in the OpenAPI docs without a specific order, other than their type:

• path
• query
• headers
• cookie

In particular, to build the OpenAPI documentation for every route, the parameters are retrieved from each route (and related dependencies), and duplicated parameters are removed with dictionary comprehension.

Problem In case there are multiple parameters, it may be a lot easier to show them sorted alphabetically in the documentation (with respect their type, so path params before query params for example). Also, the current order is not specified, since dictionary elements are in insertion order and it is not really clear how to control that. A better alternative (and easier to read in the doc) is to sort them by alphabetic order.

Example of parameters, taken directly from the current tutorial's tests:

"parameters": [
                    {
                        "required": False,
                        "schema": {"title": "Q", "type": "string"},
                        "name": "q",
                        "in": "query",
                    },
                    {
                        "required": False,
                        "schema": {"title": "Skip", "type": "integer", "default": 0},
                        "name": "skip",
                        "in": "query",
                    },
                    {
                        "required": False,
                        "schema": {"title": "Limit", "type": "integer", "default": 100},
                        "name": "limit",
                        "in": "query",
                    }
                ]

Solution To fix this problem and have the parameters for each route nicely ordered by their name, it's sufficient to sort the parameters by the alias property when they are fetched from the routes.

The above piece of OpenAPI would become:

"parameters": [
                    {
                        "required": False,
                        "schema": {"title": "Limit", "type": "integer", "default": 100},
                        "name": "limit",
                        "in": "query",
                    },
                    {
                        "required": False,
                        "schema": {"title": "Q", "type": "string"},
                        "name": "q",
                        "in": "query",
                    },
                    {
                        "required": False,
                        "schema": {"title": "Skip", "type": "integer", "default": 0},
                        "name": "skip",
                        "in": "query",
                    },
                ]

Caveats I thought about two possible caveats:

1. There may be use-cases where someone would want parameters ordered with the current logic, which is by definition (e.g. parameter A is shown before parameter B if is defined before).
2. Some images in the repo would currently not be up-to-date (the order of parameters could be different), but I don't think it should be a big problem.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Comparison is base (cf73051) 100.00% compared to head (f23cd3f) 100.00%. Report is 1036 commits behind head on master.

:exclamation: Current head f23cd3f differs from pull request most recent head dc3905d. Consider uploading reports for the commit dc3905d to get more accurate results

Additional details and impacted files

@@             Coverage Diff             @@
##            master     #2337     +/-   ##
===========================================
  Coverage   100.00%   100.00%             
===========================================
  Files          540       240    -300     
  Lines        13969      7101   -6868     
===========================================
- Hits         13969      7101   -6868     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[Mause]

A small note

since dictionaries elements are not ordered.

This changed several python versions ago, dictionary elements are now in insertion order

[klaa97]

A small note

since dictionaries elements are not ordered.

This changed several python versions ago, dictionary elements are now in insertion order

Thank you - I wasn't aware of the change. I will update the PR (I would insert the sorting inside the get_flat_params function instead, to maintain the order of the various type of parameters). Also, if I'm understanding correctly, there could a name clash (for example between query, path or header parameters) and the parameters wouldn't be shown inside OpenAPI, but I'd leave that for another PR 🤔

[github-actions[bot]]

📝 Docs preview for commit f23cd3fae6d4962211652bf7533f4d0bce806365 at: https://5fafb0cbcf2b1ce58c91409b--fastapi.netlify.app

[falkben]

maybe nice to have the option to use the original ordering? or to specify order?

[klaa97]

maybe nice to have the option to use the original ordering? or to specify order?

I was thinking that alphabetical order in each parameter group is a better default - note that it's always possible to have the option to have any order extending the OpenAPI documentation.

[ArcLightSlavik]

@tiangolo #3300 is a slightly different implementation of this, pinging so u know there's a few optinos to pick from 🚀

[github-actions[bot]]

📝 Docs preview for commit 32218162df21c5fe94d4311af7e0d504aee28053 at: https://631e12709e1ad245d8a7b08d--fastapi.netlify.app

[github-actions[bot]]

📝 Docs preview for commit 8d29b2992189c5ba59b46f0cbd0d5c0ca231f2f9 at: https://638366ba89f64174f6e8f980--fastapi.netlify.app