J'ai utilisé sphinx pour documenter notre API. Comme on peut s'y attendre, il y a certains paramètres dans notre API pour lesquels les valeurs sont un ensemble restreint. Par exemple, il peut y avoir un paramètre "on" pour une publication qui décrit une télévision, et le même paramètre peut être disponible pour le filtrage sur un GET.Sphinx décrit des valeurs d'entrée valides à api
Mon problème a été que je ne trouve pas de manière intégrée pour décrire les valeurs de paramètres valides. Pour les booléens, je vais juste le mettre en parens, mais certains paramètres ont 20 valeurs d'entrée valides, et certains ont plusieurs ensembles possibles de paramètres d'entrée en fonction de la valeur de plusieurs points variables dans la route. Par exemple:
myapi.com/<string:gameConsoleId>/games/<string:gameId>
En interne, nous ne permettent pas de valeur possible pour gameConsoleId ou gameId. Nous voulons un gameConsoleId pour être un PLAYSTATION, ou un XBOX, ou un NINTENDO. La même chose est vraie de gameId. Si vous passez un jeu mario à une console Playstation, il devrait retourner une erreur, et nous voulons documenter cela.
Est-ce un signe que l'API doit être conçue différemment, ou est-ce que je manque juste comment faire les normes de documentation?
Pour être plus clair, j'essaie de comprendre comment faire quelque chose dans Sphinx. Spécifiquement, je cherche la syntaxe, les commandes, ou les normes correctes pour documenter les paramètres d'entrée valides à un point final d'api. Il est clair pour moi de documenter qu'il existe un paramètre d'entrée valide.
paramètre de chaîne de requête:
:query gameConsoleId: The type of game console
Json Paramètre (POST etc):
:<json string gameConsoleId: The type of game console
Ce qui est moins clair pour moi est de savoir comment documenter les valeurs valides pour les entrées. Nous avons défini des entrées valides, il n'est pas clair pour moi comment communiquer cela via Sphinx.
Par exemple, ci-dessous sont les entrées valides pour gameConsoleId:
[PLAYSTATION,XBOX,NINTENDO]
Peut-être une meilleure question pour [programmers.SE] (http://programmers.stackexchange.com/) si vous posez des questions sur la documentation et la conception. – Celeo
Si cela concerne principalement le sphinx, il s'agirait plutôt d'un problème de mise en œuvre et de discussion sur le sujet ici à SO. Si c'est avant tout de la documentation et de la conception, ça va probablement convenir à Progs comme l'appelle @Celeo. – GlenH7
'Je ne trouve pas de méthode intégrée pour décrire les valeurs de paramètres valides' - Cela me semble être une validation banale. Ou demandez-vous autre chose, comme une URL REST auto-documentée par rapport à ses valeurs valides? –