web-dev-qa-db-fra.com

Comment diviser le fichier JSON swagger 2.0 en plusieurs modules

J'essaie de diviser mon document API en plusieurs fichiers JSON qui peuvent être modifiés indépendamment. Tous les exemples que j'ai pu trouver utilisent le schéma Swagger 1.2 qui a un objet "api": {} pour le décomposer. Cela semble manquer dans le schéma 2.0 ( http://json.schemastore.org/swagger-2. ). Tout ce qui définit est un tableau de "chemins" unique où il regroupe tous les points de terminaison API dans ce tableau unique. L'effet de cela dans le swagger-ui est qu'il y a une seule catégorie "par défaut" dans laquelle tout est intégré et aucun moyen que je puisse dire de le diviser.

TLDR: comment séparer les opérations des chemins dans le schéma swagger 2.0

{
  "swagger": "2.0",
  "info": {
    "description": "My API",
    "version": "1.0.0",
    "title": "My API",
    "termsOfService": "http://www.domain.com",
    "contact": {
      "name": "[email protected]"
    }
  },
  "basePath": "/",
  "schemes": [
    "http"
  ],
  "paths": {
    "Authorization/LoginAPI": {
      "post": {
        "summary": "Authenticates you to the system and produces a session token that will be used for future calls",
        "description": "",
        "operationId": "LoginAPI",
        "consumes": [
          "application/x-www-form-urlencoded"
        ],
        "produces": [
          "application/json"
        ],
        "parameters": [{
          "in": "formData",
          "name": "UserName",
          "description": "Login Username",
          "required": true,
          "type": "string"

        }, {
          "in": "formData",
          "name": "Password",
          "description": "Password",
          "required": true,
          "type": "string"

        }],
        "responses": {
          "200": {
            "description": "API Response with session ID if login is allowed",
            "schema": {
              "$ref": "#/definitions/Authorization"
            }
          }
        }
      }
    }
  }
}
swaggerswagger-uiswagger-2.0
35
John P

En fait, vous posez plusieurs questions en une, et je vais essayer de répondre à toutes.

Dans Swagger 1.2 et avant celui-ci, le fractionnement des fichiers était obligatoire et artificiel. C'était censé être un moyen de regrouper les opérations, et Swagger 2.0 propose et une méthode alternative pour le faire (plus de détails bientôt).

Swagger 2.0 est en effet un fichier unique, qui permet des fichiers externes partout où $ref est utilisé. Vous ne pouvez pas diviser un seul service en plusieurs fichiers et les combiner en un seul, mais vous pouvez spécifier des opérations pour des chemins spécifiques en externe (à nouveau, en utilisant le $ref propriété).

Nous sommes actuellement en train de finaliser la possibilité de rassembler plusieurs micro-services dans une seule collection, mais à terme, chaque micro-service restera un fichier unique.

Comme mentionné, le regroupement des opérations dans Swagger 2.0 a changé et le concept de "ressource" n'existe plus. À la place, il existe des balises (avec le "tags" propriété) qui peut être affectée par opération. tags est un tableau de valeurs, et contrairement aux versions précédentes, chaque opération peut exister sous plusieurs balises si nécessaire. Dans Swagger-UI, toutes les opérations qui n'ont pas de balises définies se retrouveront sous la balise default, qui est le comportement que vous avez vu. Il existe une propriété tags supplémentaire dans l'objet de niveau supérieur qui vous permet d'ajouter des descriptions aux balises et de définir leur ordre, mais il n'est pas obligatoire de l'inclure.

Pour terminer, je n'ai aucune idée de la façon dont le schéma json de Swagger 2.0 s'est retrouvé dans http://json.schemastore.org/swagger-2. mais il n'est certainement pas à jour. Le schéma le plus récent peut être trouvé ici - http://swagger.io/v2/schema.json - et il est toujours en cours de développement. Gardez à l'esprit que la source de la vérité est la spécification ( https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md ) et non le schéma, donc en cas de conflits, la spécification "gagne".

Modifier:

Nous venons de publier un guide sur le référencement. Cela peut aider dans certains cas d'utilisation - https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/v2.0/REUSE.md

27
Ron

J'ai écrit à ce sujet dans cet article de blog . Vous pouvez essentiellement utiliser la bibliothèque JSON Refs pour résoudre tous vos petits fichiers Swagger en un seul grand et l'utiliser dans les outils.

10
Mohsen

Si les références JSON ne fonctionnaient pas pour vous, il pourrait être utile d'écrire votre propre concaténateur. Eh bien, au lieu d'écrire le vôtre, vous pouvez réellement utiliser quelque chose qui existe déjà. N'importe quel moteur de template fera l'affaire. Dans mon cas, les guidons se sont avérés très utiles (car les guidons préservent en fait l'indentation, ce qui est parfait pour les fichiers Yaml car ils sont sensibles à la casse).

Ensuite, vous pouvez avoir un script de construction dans Node:

'use strict';

var hbs = require('handlebars');
var fs  = require('fs');

var dir = __dirname + '/your_api_dir';

var files = fs.readdirSync(dir);

files.forEach((fileName) => {
  var raw = fs.readFileSync(dir + '/' + fileName, 'utf8');
  hbs.registerPartial(file, raw);
});

var index = fs.readFileSync(dir + '/index.yaml');

var out = hbs.compile(index.toString());

En savoir plus sur le problème sur mon blog .

2
Oleg Berman

Notez que RepreZen API Studio prend désormais en charge les projets multi-fichiers Swagger/Open API via le $ref syntaxe discutée ici. Vous pouvez donc diviser les grands projets Swagger en modules pour permettre la réutilisation et la collaboration d'équipe. Vous pouvez ensuite utiliser le normalisateur Swagger intégré pour créer un fichier Swagger unique et consolidé lorsque vous devez sortir votre modèle d'API de l'environnement de conception/développement.

Remarque: dans l'intérêt d'une divulgation complète, je suis chef de produit chez RepreZen. Je suis tombé sur ce sujet la semaine dernière et j'ai pensé que j'allais y participer.

2
daffinm

J'ai écrit un préprocesseur Swagger/OpenAPI pour faciliter la rédaction des spécifications.

https://github.com/dolmen-go/openapi-preprocessor/

Il prend notamment en charge $ref pointant vers des fichiers externes et permet de modifier vos spécifications en plusieurs fichiers, mais de produire un seul fichier pour une compatibilité maximale avec les outils qui le consommeront.

1
dolmen

J'essaie également de comprendre cela, et il y a quelques informations utiles dans le Swagger Google group . Il semble que le consensus soit que vous pouvez diviser les définitions en fichiers séparés tant que $ ref pointe vers une URL absolue. Exemple ici:

https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions.json#L32

https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/resources/resourceWithLinkedDefinitions_part1.json

1
Bailey Smith

Si json ne fonctionne pas pour vous bis, vous pouvez également et vous utilisez node.js, vous pouvez également utiliser module.exports

J'ai mes définitions dans des modules, et je peux exiger un module dans un module:

const params = require(./parameters);
module.exports = {
  description: 'Articles',
  find: {
    description: 'Some description of the method', 
    summary: 'Some summary',
    parameters: [
        params.id,
        params.limit,


...
0
Samuel