Hola,
No sé si esto es un error o una mejora, pero aquí está
Digamos que quiero crear una API con cuatro rutas:
POST /bar
GET /bar/{id_bar}
POST /foo
GET /foo/{id_foo}
Pero consideremos que los inserto usando la interfaz de usuario en este orden específico:
GET /foo/{id_foo}
POST /bar
GET /bar/{id_bar}
POST /foo
La interfaz de usuario es agradable y las rutas aparecen ordenadas, coincidiendo con lo que quiero:
Pero, el yml resultante no está ordenado y no coincide con lo que aparece en la interfaz de usuario:
openapi: 3.0.2
info:
title: 'Test API'
version: 1.0.0
paths:
'/foo/{id_foo}': {}
/bar: {}
'/bar/{id_bar}': {}
/foo: {}
Normalmente, no me importaría el orden de las rutas en el archivo yml sin procesar.
Pero la cosa es que ReDoc sigue el orden de las rutas en el yml
Por lo que la documentación resultante no está ordenada:
Esto es un problema porque una vez que una API comienza a vivir, algunas rutas se actualizan, algunas se eliminan y otras se crean.
Esto significa que la documentación resultante se está convirtiendo rápidamente en un desorden confuso.
Tengo algunas ideas, están lejos de ser perfectas, pero es un comienzo.
Tal vez podamos construir sobre ellos y elaborar
Vaya, lo siento, olvidé adjuntar el YML que usé para las capturas de pantalla de ReDoc
(El que pegué no tiene operaciones, por lo que ReDoc genera un documento vacío)
openapi: 3.0.2
info:
title: 'Test API'
version: 1.0.0
paths:
'/foo/{id_foo}':
get:
summary: 'Obtain a foo'
parameters:
-
name: id_foo
in: path
required: true
schema:
type: number
responses:
'201':
description: 'A foo'
/bar:
post:
summary: 'Create a bar'
responses:
'200':
description: 'A bar'
'/bar/{id_bar}':
get:
summary: 'Obtain a bar'
parameters:
-
name: id_bar
in: path
required: true
schema:
type: number
responses:
'201':
description: 'Bar created'
/foo:
post:
summary: 'Create a foo'
responses:
'200':
description: 'Foo created'
¡Este es un tema interesante que sorprendentemente no ha surgido antes! En realidad, hay algunos lugares en la interfaz de usuario donde creo que deberíamos proporcionar su opción C: mostrar los elementos en el orden en que aparecen en el documento pero ofrecer opciones para ordenar y reordenar (arrastrar y soltar, presumiblemente).
Dicho esto, una solución temporal sería ordenar las rutas y otras listas antes de entregar el contenido a ReDoc. Eso sería rápido y fácil de hacer y solucionaría el problema específico de la función "Vista previa" de Apicurio.
¿Alguna idea/pensamiento sobre esto, @jsenko ?
También me encontré con estos problemas; mi observación sobre esto es que APICURIO simplemente agrega una nueva definición al YAML actual cuando creamos nuevas rutas; o cuando reemplazamos totalmente yaml (por ejemplo, para una ruta individual si modifico algo desde la pestaña 'fuente').
Manipulo manualmente la base de datos para solucionar esto después de modificar YAML yo mismo (luego actualizo la columna) y, de alguna manera, todo se rompe y tengo que eliminar el proyecto y reiniciarlo nuevamente.
Como dijo @EricWittmann , creo que es mejor ordenar las rutas y otras listas antes de entregar el contenido a ReDoc, o podríamos usar otro botón en la pestaña 'fuente' al lado del botón 'Formato' (tal vez nombrando como 'Ordenar rutas'), que podemos manejar por nosotros mismos.
Como #394, creo que la idea general aquí es que la interfaz de usuario de Apicurio debería corresponder con el orden YAML para todo tipo de elementos (rutas, campos, probablemente tipos de datos) porque ese orden a veces es importante (como para generar documentación).
Una cosa simple que sería útil aquí es habilitar el botón Guardar al editar el YAML sin procesar y cambiar solo el orden de los elementos. Actualmente, Apicurio es demasiado inteligente y atenúa el botón Guardar cuando lo único que ha cambiado es el orden de los elementos.
Creo que lo mejor es ordenar en la interfaz de usuario para que coincida con la fuente (como se mencionó) y que los usuarios puedan mover cosas mediante arrastrar y soltar. Ese no es un cambio trivial, pero es lo correcto en mi opinión. ¿Pensamientos @jsenko ?
Comentario más útil
También me encontré con estos problemas; mi observación sobre esto es que APICURIO simplemente agrega una nueva definición al YAML actual cuando creamos nuevas rutas; o cuando reemplazamos totalmente yaml (por ejemplo, para una ruta individual si modifico algo desde la pestaña 'fuente').
Manipulo manualmente la base de datos para solucionar esto después de modificar YAML yo mismo (luego actualizo la columna) y, de alguna manera, todo se rompe y tengo que eliminar el proyecto y reiniciarlo nuevamente.
Como dijo @EricWittmann , creo que es mejor ordenar las rutas y otras listas antes de entregar el contenido a ReDoc, o podríamos usar otro botón en la pestaña 'fuente' al lado del botón 'Formato' (tal vez nombrando como 'Ordenar rutas'), que podemos manejar por nosotros mismos.