Apicurio-studio: El orden de la ruta en la API yml no está ordenado y no coincide con la ruta en la interfaz de usuario

Creado en 12 mar. 2019  ·  5Comentarios  ·  Fuente: Apicurio/apicurio-studio

Hola,

No sé si esto es un error o una mejora, pero aquí está

Descripción del problema

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:

image

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:

image

image

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.

Qué se puede hacer

Tengo algunas ideas, están lejos de ser perfectas, pero es un comienzo.
Tal vez podamos construir sobre ellos y elaborar

  • Ordenar siempre la API de salida
    Pros: fácil de implementar (¿creo?)
    Contras: los usuarios no pueden elegir su propio pedido
  • Agregue una opción para ordenar las rutas en la API de salida
    Pros: fácil de implementar (¿creo?)
    Contras: el usuario no puede cambiar el orden de las rutas individuales
  • Modifique la interfaz de usuario para que las rutas mostradas no estén ordenadas,
    y agregue un botón para ordenar todo + botones para mover rutas individuales hacia arriba y hacia abajo
    Ventajas: Solucionaría todo
    Contras: más difícil de implementar (¿creo?)
enhancement

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.

Todos 5 comentarios

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 ?

¿Fue útil esta página
0 / 5 - 0 calificaciones