Api.raml doit-il contenir toute l'API?

Question

J'ai une question simple à propos de RAML (RESTful Api Modeling language). Je voulais essayer quelque chose de nouveau afin de créer une documentation pour mon API (et ensuite la tester). L'API est écrite dans node.js.

Dois-je inclure tout mon code dans le fichier api.raml? Ou est-il possible d'importer des sous-routes à partir d'autres fichiers .raml? Y a-t-il de bonnes directives pour diviser les fichiers .raml?

par exemple. Je voudrais créer un fichier appelé books.raml. Il inclurait toutes les routes sous /books. Puis plus tard, je veux l'importer dans mon api.raml, donc ce serait plus comme un fichier qui ne comprend que des sous-fichiers.

Est-ce correct? Si oui, comment pourrais-je faire cela et quelles sont les lignes directrices sur l'endroit où stocker ces fichiers (dans quel répertoire)?

Answer 1

Vous pouvez diviser votre spécification RAML en plusieurs fichiers et utiliser la directive ! Include pour inclure des fichiers.

Par exemple:

#%RAML 1.0 
title: My API with Types 
types: !include myTypes.raml 

En savoir plus sur comprend here

En outre RAML fournit des bibliothèques: « les bibliothèques de Raml sont utilisées pour combiner une collection de déclarations de type de données, déclarations de type de ressources, les déclarations de trait, et les déclarations de schémas de sécurité dans des groupes modulaires, externalisés et réutilisables "

Quoi et comment utiliser dépend de votre cas d'utilisation. Mais je pense que les bibliothèques peuvent fournir une structure meilleure/plus significative.

Vérifiez la section sur modularization pour plus d'informations.

Vous pouvez également inclure les routes comme vous dites, par exemple .:

#%RAML 1.0 
title: bla 
/foo/: 
    /bar/: 
    post: 
    get: 
/books: !include books.raml 

Mais je ne suis pas sûr que c'est une bonne façon de structurer votre RAML.