Apicurio-studio: Referências de suporte a objetos de componentes em documentos de especificação

Caso de uso

O principal caso de uso que isso resolverá é dar aos usuários a capacidade de centralizar suas definições de tipo de dados, talvez em um único arquivo (ou um conjunto de arquivos). Esses tipos de dados podem ser aproveitados em várias definições de API fazendo referência à sua localização central.

Considerações

Para oferecer suporte a referências externas, são necessários vários aprimoramentos. Aqui está uma lista em nenhuma ordem específica:

• A biblioteca de modelo de dados (atualmente oai-ts-core mas em breve será apicurio-data-models ) deve ser aprimorada para oferecer suporte a um resolvedor de referência conectável. Atualmente, essas bibliotecas são capazes de resolver apenas referências internas. Em vez disso, um consumidor da biblioteca deve ser capaz de fornecer um resolvedor de referência personalizado para que as referências externas possam ser resolvidas com êxito.

• O Apicurio Studio deve oferecer suporte a um recurso de estilo "somente tipo de dados", com um editor focado no design de tipos de dados. Isso permite um fluxo de trabalho mais específico para criar/gerenciar tipos de dados independentemente dos designs de API.

• Ao definir um tipo no editor de design de API, o conjunto de ferramentas precisa de uma maneira de selecionar tipos de recursos externos. Precisamos considerar a melhor forma de exibir esses tipos externos ao usuário para seleção. Pode ser que precisemos de uma maneira para os designs de API "importarem" outros recursos/arquivos para que a interface do usuário possa restringir as opções para o usuário e exibi-las de maneira sensata. Lembre-se de que o editor precisaria buscar e analisar quaisquer recursos externos para exibir seus tipos de dados disponíveis em algum tipo de controle de IU de seleção.

• Talvez precisemos decidir se os recursos de tipo de dados em andamento podem ser usados ​​como fonte para referências externas em um design de API. Em outras palavras, deveria ser possível fazer referência a tipos de dados "instantâneos" em um design de API? Ou devemos exigir que um recurso Data Type seja "final" antes que possa ser usado como fonte para referências externas. Se for o primeiro, não podemos "finalizar" um design de API até que suas dependências também sejam finalizadas. Nota: todo este conceito exige que implementemos os recursos de finalização no Apicurio!

• Precisaremos decidir qual será o formato $ref ao fazer referência aos recursos do Apicurio. Atualmente, qualquer design de API (ou recurso teórico de tipos de dados) tem um ID exclusivo, mas é um ID opaco que é gerado na criação. Essa ID é atualmente a única maneira exclusiva de identificar um recurso para fins de resolução. Depois que um recurso é finalizado (se apoiarmos esse conceito), talvez possamos conceder ao recurso um identificador mais amigável e usá-lo no URI $ref. O que quer que façamos, deve-se notar que, ao publicar um recurso em um registro de API (outro recurso futuro), quaisquer $references no design de API precisarão ser resolvidos pelo registro de API de alguma maneira sensata.

Aqui estão algumas informações sobre os valores permitidos para um $ref :

Mesmo que o valor de um $ref seja um URI, ele não é um localizador de rede, apenas um identificador. Isso significa que o esquema não precisa estar acessível nesse URI, mas pode ser. Depende basicamente da implementação do validador como os URIs do esquema externo serão tratados, mas não se deve presumir que o validador buscará os recursos de rede indicados nos valores $ref.

Mais informações sobre referências podem ser encontradas na especificação OpenAPI e no JSON Reference RFC .

Seria possível priorizar a implementação de referências a DataTypes de outra especificação dentro do Apicurio (em vez de referências externas inicialmente)?

A razão pela qual digo isso é que alguma funcionalidade de referência cruzada é necessária para qualquer uso não trivial do Swagger. Por exemplo, estamos implementando vários serviços que compartilham tipos de dados (por exemplo, endereços, pessoas etc.) e gostaríamos de usar o Apicurio para as especificações de todos eles. No entanto, no momento não podemos por causa da incapacidade de usar referências cruzadas.

Seria possível priorizar a implementação de referências a DataTypes de outra especificação dentro do Apicurio (em vez de referências externas inicialmente)?

A razão pela qual digo isso é que alguma funcionalidade de referência cruzada é necessária para qualquer uso não trivial do Swagger. Por exemplo, estamos implementando vários serviços que compartilham tipos de dados (por exemplo, endereços, pessoas etc.) e gostaríamos de usar o Apicurio para as especificações de todos eles. No entanto, no momento não podemos por causa da incapacidade de usar referências cruzadas.

Concordo, isso nos levaria ao território de aplicativos matadores.

@jsenko Parece que, uma vez que encerramos o registro impl, temos uma prioridade clara da comunidade. :)

eu adoraria ver isso, usar apicurio no trabalho e referências seriam incrivelmente úteis para diferentes equipes.

Eu percebo que isso demorou um pouco, mas referências externas serão oficialmente suportadas a partir do Beta 2.46, que é o próximo lançamento (esperamos que seja feito amanhã). Há uma nova interface do usuário para importar tipos de dados e respostas de outros documentos do Apicurio Studio para o atual. Além disso, a validação foi atualizada para suportar a resolução de http/s externos, bem como referências internas do Apicurio. Este deve ser um bom primeiro passo para um suporte maduro para referências entre documentos.