multiple - swagger validator
Cómo romper swagger 2.0 JSON archivo en múltiples módulos (6)
En realidad, haces varias preguntas en una, e intentaré responderlas todas.
En Swagger 1.2 y antes de esto, la división del archivo era obligatoria y artificial. Fue concebido como una forma de agrupar operaciones, y Swagger 2.0 ofrece un método alternativo para hacerlo (más sobre esto pronto).
Swagger 2.0 es de hecho un solo archivo, que permite archivos externos donde se usa $ref . No puede dividir un solo servicio en varios archivos y combinarlos como uno, pero puede especificar operaciones para rutas específicas externamente (nuevamente, usando la propiedad $ref ).
Actualmente estamos en el proceso de finalizar la capacidad de reunir varios micro servicios en una única colección, pero eventualmente, cada microservicio seguirá siendo un único archivo.
Como se mencionó, la agrupación de operaciones en Swagger 2.0 ha cambiado, y el concepto de ''recurso'' ya no existe. En cambio, hay etiquetas (con la propiedad "tags" ) que se pueden asignar por operación. Las tags son una matriz de valores y, a diferencia de las versiones anteriores, cada operación puede existir bajo varias etiquetas si es necesario. En Swagger-UI, todas las operaciones que no tienen etiquetas definidas terminarán bajo la etiqueta default , que es el comportamiento que ha visto. Hay una propiedad de tags adicional en el objeto de nivel superior que le permite agregar descripciones a las etiquetas y establecer su orden, pero no es obligatorio incluirlas.
Como nota final, no tengo idea de cómo el esquema json de Swagger 2.0 terminó en http://json.schemastore.org/swagger-2.0 pero ciertamente no está actualizado. El esquema más actualizado se puede encontrar aquí - http://swagger.io/v2/schema.json - y todavía está en desarrollo. Tenga en cuenta que la fuente de la verdad es la especificación ( https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md ) y no el esquema, por lo que en caso de conflictos, el spec ''gana''.
Editar:
Acabamos de publicar una guía sobre referencias. Puede ayudar con algunos casos de uso: https://github.com/OAI/OpenAPI-Specification/blob/master/guidelines/v2.0/REUSE.md
Estoy intentando dividir mi documento API en varios archivos JSON que se pueden editar de forma independiente. Todos los ejemplos que he podido encontrar utilizan el esquema de Swagger 1.2 que tiene un objeto "api": {} para descomponerlo. Parece que falta en el esquema 2.0 ( http://json.schemastore.org/swagger-2.0 ). Todo lo que define es una única matriz de "rutas" donde agrupa todos los puntos finales API en esa única matriz. El efecto de esto en el swagger-ui es que hay una sola categoría "predeterminada" en la que todo se incluye y no hay forma de que sepa dividirla.
TLDR: ¿Cómo se dividen las operaciones de las rutas en el esquema de 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"
}
}
}
}
}
}
}
Estoy tratando de resolver esto también, y hay algo de información útil en el grupo de Swagger Google . Parece que el consenso es que puede dividir las definiciones en archivos separados siempre que $ ref esté apuntando a una url absoluta. Ejemplo aquí:
He escrito sobre esto en esta publicación de blog . Básicamente puede usar la biblioteca JSON Refs para resolver todos sus pequeños archivos Swagger en uno grande y usarlo en las herramientas.
Si json no funciona para usted, también puede usar node.js y también puede usar module.exports
Tengo mis definiciones en módulos y puedo solicitar un módulo dentro de un módulo:
const params = require(./parameters);
module.exports = {
description: ''Articles'',
find: {
description: ''Some description of the method'',
summary: ''Some summary'',
parameters: [
params.id,
params.limit,
...
Si las referencias JSON no le funcionaron, podría ser útil escribir su propio concatenador. Bueno, en lugar de escribir el tuyo, puedes usar algo que ya está disponible. Cualquier motor de plantillas lo hará. En mi caso, los manubrios resultaron ser muy útiles (porque Handlebars en realidad conserva la indentación, que es perfecta para los archivos Yaml ya que distinguen entre mayúsculas y minúsculas).
Entonces puedes tener un script de compilación en 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());
Lea más sobre el tema en mi blog .
Tenga en cuenta que RepreZen API Studio ahora admite proyectos Swagger / Open API de varios archivos a través de la sintaxis de $ref trata aquí. De modo que puede dividir grandes proyectos de Swagger en módulos para permitir la reutilización y la colaboración en equipo. A continuación, puede utilizar el normalizador Swagger incorporado para crear un único archivo Swagger consolidado cuando necesite sacar su modelo API fuera del entorno de diseño / desarrollo.
Nota: en aras de una divulgación completa, soy Product Manager en RepreZen. Me tropecé con este hilo la semana pasada y pensé en ingresar.