Apicurio-studio: Admite referencias a objetos de componentes en documentos de especificación

Caso de uso

El principal caso de uso que esto resolverá es dar a los usuarios la capacidad de centralizar sus definiciones de tipos de datos, quizás en un solo archivo (o un conjunto de archivos). Estos tipos de datos se pueden aprovechar en múltiples definiciones de API haciendo referencia a su ubicación central.

Consideraciones

Para admitir referencias externas, se necesitan una serie de mejoras. Aquí hay una lista sin ningún orden en particular:

• La biblioteca del modelo de datos (actualmente oai-ts-core pero pronto será apicurio-data-models ) debe mejorarse para admitir una resolución de referencia conectable. Actualmente, estas bibliotecas solo pueden resolver referencias internas. En su lugar, un consumidor de la biblioteca debe poder proporcionar una resolución de referencia personalizada para que las referencias externas puedan resolverse correctamente.

• Apicurio Studio debe admitir un recurso de estilo "solo tipo de datos", con un editor que se centre en el diseño de tipos de datos. Esto permite un flujo de trabajo más específico para crear/administrar tipos de datos independientemente de los diseños de API.

• Al configurar un tipo en el editor de diseño de API, las herramientas necesitan una forma de seleccionar tipos de recursos externos. Necesitamos considerar la mejor manera de mostrar estos tipos externos al usuario para su selección. Puede ser que necesitemos una forma para que los diseños de API "importen" otros recursos/archivos para que la interfaz de usuario pueda reducir las opciones para el usuario y mostrarlas con sensatez. Tenga en cuenta que el editor necesitaría buscar y analizar cualquier recurso externo para mostrar sus tipos de datos disponibles en algún tipo de control de IU de selección.

• Es posible que debamos decidir si los recursos de tipo de datos en progreso se pueden usar como fuente para referencias externas en un diseño de API. En otras palabras, ¿debería ser posible hacer referencia a tipos de datos de "instantánea" en un diseño de API? ¿O deberíamos requerir que un recurso de tipo de datos sea "final" antes de que pueda usarse como fuente para referencias externas? Si es lo primero, entonces no podemos "finalizar" un diseño de API hasta que sus dependencias también estén finalizadas. Nota: ¡todo este concepto requiere que implementemos recursos de finalización en Apicurio!

• Tendremos que decidir cuál será el formato $ref al hacer referencia a los recursos de Apicurio. Actualmente, cualquier diseño de API (o recurso de tipos de datos teóricos) tiene una identificación única, pero es una identificación opaca que se genera al momento de la creación. Ese ID es actualmente la única forma única de identificar un recurso con fines de resolución. Una vez que se finaliza un recurso (si apoyamos ese concepto), entonces tal vez podríamos otorgar al recurso un identificador más amigable para los humanos y luego usarlo en el URI $ref. Hagamos lo que hagamos, debe tenerse en cuenta que al publicar un recurso en un registro de API (otra característica futura), cualquier $referencia en el Diseño de API deberá ser resuelta por el registro de API de alguna manera sensata.

Aquí hay información sobre los valores permitidos para $ref :

Aunque el valor de $ref es un URI, no es un localizador de red, solo un identificador. Esto significa que no es necesario que el esquema sea accesible en ese URI, pero puede serlo. Básicamente, depende de la implementación del validador cómo se manejarán los URI de esquema externo, pero uno no debe asumir que el validador obtendrá los recursos de red indicados en los valores de $ref.

Puede encontrar más información sobre las referencias en la especificación de OpenAPI y el RFC de referencia de JSON .

¿Sería posible priorizar la implementación de referencias a DataTypes desde otra especificación dentro de Apicurio (en lugar de referencias externas inicialmente)?

La razón por la que digo esto es que se necesita alguna funcionalidad de referencia cruzada para cualquier uso no trivial de Swagger. Por ejemplo, estamos implementando varios servicios que comparten tipos de datos (por ejemplo, direcciones, personas, etc.) y nos gustaría utilizar Apicurio para las especificaciones de todos ellos. Sin embargo, por el momento no podemos debido a la imposibilidad de utilizar referencias cruzadas.

¿Sería posible priorizar la implementación de referencias a DataTypes desde otra especificación dentro de Apicurio (en lugar de referencias externas inicialmente)?

La razón por la que digo esto es que se necesita alguna funcionalidad de referencia cruzada para cualquier uso no trivial de Swagger. Por ejemplo, estamos implementando varios servicios que comparten tipos de datos (por ejemplo, direcciones, personas, etc.) y nos gustaría utilizar Apicurio para las especificaciones de todos ellos. Sin embargo, por el momento no podemos debido a la imposibilidad de utilizar referencias cruzadas.

De acuerdo, esto nos llevaría al territorio de las aplicaciones asesinas.

@jsenko Parece que una vez que

Me encantaría ver esto, usar apicurio en el trabajo y las referencias serían increíblemente útiles para diferentes equipos.

Me doy cuenta de que esto ha tardado un poco, pero las referencias externas se admitirán oficialmente a partir de la versión Beta 2.46, que es la próxima versión (con suerte, mañana). Hay una nueva interfaz de usuario para importar tipos de datos y respuestas de otros documentos de Apicurio Studio al actual. Además, la validación se ha actualizado para admitir la resolución de http/s externos, así como las referencias internas de Apicurio. Este debería ser un buen primer paso hacia un soporte maduro para referencias entre documentos.