I've been using sphinx to document our api. As one might expect, there are certain parameters in our api for whose values are a restricted set. For example, there might be an "on" parameter for a post which describes a tv, and the same parameter might be available for filtering on a GET.
My problem has been that I can't find a built-in way to describe valid parameter values. For bools I'm ok with just putting it in parens, but some parameters have 20 valid input values, and some have multiple possible sets of input params depending on the value of multiple variable points in the route. For example:
myapi.com/<string:gameConsoleId>/games/<string:gameId>
Internally, we don't allow any possible value for gameConsoleId or gameId. We want a gameConsoleId to be a PLAYSTATION, or an XBOX, or a NINTENDO. The same is true of the gameId. If you pass a mario game to a playstation console, it should return an error, and we want to document that.
Is this a sign that the api needs to be designed differently, or am I just missing how to do the documentation norms?
To be more clear, I am trying to figure out how to do something in Sphinx. Specifically, I am looking for correct syntax, commands, or norms for documenting the valid input parameters to an api endpoint. It is clear to me how to document that there is a valid input parameter.
Query string parameter:
:query gameConsoleId: The type of game console
Json Parameter (for POST etc):
:<json string gameConsoleId: The type of game console
What isn't clear to me is how to document the valid values for those inputs. We have valid inputs defined, it just isn't clear to me how to communicate that through Sphinx.
For example, below are the valid inputs to gameConsoleId:
[PLAYSTATION,XBOX,NINTENDO]
A good approach is to look at existing documentation of a popular and well-documented project such as Python itself. Python documentation uses several methods to documenting parameters that can take one of a set of values:
The mode parameter should be 'r' to read an existing file, 'w' to truncate and write a new file, or 'a' to append to an existing file.
mode may take one of the following values (as defined in the stat module) or bitwise ORed combinations of them:
In the spirit of this answer, the documentation for the numpy.array order parameter starts as follows:
order : {'K', 'A', 'C', 'F'}, optional
Here we see that the allowed values are written as the type. That is, rather than specifying that order takes the type str and then explaining what specific str values are allowed, the set of values that are allowed are listed as the type and users infer the type is str.