Api-blueprint: Modularidade

Para aquelas situações em que há um grande número de APIs, possivelmente sob o controle de diferentes grupos em uma empresa, isso seria uma dádiva absoluta.

@rurounijones apenas para esclarecimento, este recurso se destina a "para poder dividir uma descrição de API em vários arquivos".

Alguém tem alguma opinião sobre isso? De acordo com meu comentário anterior em Drafter https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28538342

As opções são adicionar algum recurso de inclusão/requerimento no topo do blueprint ou simplesmente buscar todos os blueprints de um diretório e concatená-los.

Pensamentos?

A concatenação é mais simples, mas acho que require seria mais fácil de usar, pois você pode querer exigir, depois adicione outra coisa depois.

Isso será apenas inline cegamente o conteúdo do arquivo como se fosse definido na patente, ou haverá algum tipo de restrição no conteúdo do arquivo (por exemplo, eles podem ter seu próprio cabeçalho yaml? Conflitos com o yaml pai?) Tenho a sensação de que nenhuma restrição seria melhor, mas pensei em trazer isso à tona.

@zdne

Primeiro, eu tenho um sistema rudimentar para gerenciar isso já com o Grunt, usando concatenação simples de arquivos. Nosso projeto estava se tornando incontrolável, e essa era uma maneira rápida e suja de dividi-lo em arquivos (é importante notar que muitos arquivos arbitrários, porque eles são concatenados pela ordem do sistema de arquivos). Eu postei meu Gruntfile com uma breve explicação aqui .

Dado que a concatenação é tão simples de rolar sozinho, faz sentido para mim que uma ferramenta "oficial" seja mais poderosa. Eu estive pensando mais sobre isso, tentando fazer algumas pesquisas sobre como isso é tratado por outros sistemas.

1. Incluir/Exigir
   
   
   
   • As inclusões seriam feitas na parte superior de um arquivo e partes do arquivo seriam referenciadas dentro dele. Eu acho que isso requer um sistema de referência mais robusto do que a sintaxe [Model Reference][] atual. Idealmente, qualquer nó no arquivo incluído seria endereçável - então, pode-se ter algo como [github.Users.'Create A User'][] ou [github][POST /users] ou algo assim. (Também pode precisar de um prefixo como = ). Existe uma maneira melhor de fazer referência a um nó específico no AST diferente de nome ou url + método?
   
   
   • Dado que você tem uma boa maneira de desreferenciar o conteúdo do nó, isso pode ser feito com o C Preprocessor , que vem com muitos recursos adicionais sem custo extra.
   
   
2. Sistema de modelagem/transclusão
   
   
   
   • Non-markdown - O modelo seria escrito em uma linguagem de modelagem separada, portanto, um arquivo de modelo não seria analisado pelo snowcrash. Um exemplo de algo assim é grunt-readme , que parece funcionar imediatamente para modelar um arquivo de blueprint.
   
   
   • Markdown - Isso seria algo como a sintaxe =[]() ou :[]() que discutimos sobre o problema do redator. Ainda seria uma remarcação válida e analisável pelo snowcrash.
   
   
3. Ambos
   
   
   
   • Dado que você define uma sintaxe para referenciar nós ( [github]['Create A User'] ) e transclusão direta ( :[/github.md](/github.md) ), parece que você poderia facilmente ter ambos. Talvez eles possam ter a mesma sintaxe geral como :[]() e o analisador determina se é um nó ou uma referência de arquivo.
   
   

Algum pensamento sobre isso? Estou faltando algumas opções/ferramentas? Estou meio que inclinado para a opção "ambos" com uma sintaxe comum para transclusão e desreferência de nó, mas talvez seja um pouco demais.

Dado que a concatenação é tão simples de rolar sozinho, faz sentido para mim que uma ferramenta "oficial" seja mais poderosa

Bem, eventualmente, talvez sim, mas eu gostaria de não projetar demais e lançar algo enxuto e simples no começo.

Olhando para os problemas apresentam problemas que precisam ser abordados, é principalmente:

1. Ativos (externos) referenciados - nº 20 e conforme discutido em https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071
2. Dividindo o blueprint em partes lógicas mais gerenciáveis

Para fins de divisão, eu consideraria apenas um Grupo de Recursos ou um Recurso (por exemplo, não uma ação, exemplo de transação ou solicitação). Pelo menos no início.

Anúncio 1: acho que os _ativos referenciados_ seriam abordados com elegância pela proposta no nº 20 e discutidos https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071

Anúncio 2: Eu não complicaria nada. A única coisa que eu usaria para transclusão é a sintaxe de remarcação regular, por exemplo [Some Text](path/to/blueprint/file.apib) ou [Some Text](path/to/blueprint/file.apib#resource-name) . Para inclusão, eu seguiria o mesmo princípio que para ativos no redactor, por exemplo, use : antes da referência. Algo como https://gist.github.com/zdne/8804418#aliens -question-aliens_question

Eu acho que isso poderia ser suficiente para o início?

Eu acho que isso poderia ser suficiente para o início?

Acordado. Só agora estou percebendo que você está fazendo uma distinção entre incluir "ativos" e incluir "recursos"/"grupos de recursos". Eu estava pensando em todos eles como "nós" a serem incluídos à vontade.

Para o segundo ponto, achei que seria útil fazer referência à sintaxe MultiMarkdown existente para transclusão:

This is some text.

{{some_other_file.txt}}

Another paragraph

Isso parece uma maneira simples de incluir recursos? (ou mesmo, texto/nós arbitrários?)

Então para esclarecer minha opinião:

1. Acho que uma boa sintaxe para ativos referenciados seria :[]() ou =[]() conforme discutido
2. Eu acho que uma boa sintaxe para transclusão seria {{ }} como usado por multimarkdown.

E também para esclarecer um pouco de vocabulário: eu _acho_ que quando você diz "inclusão" você está se referindo ao que eu quero dizer quando digo "transclusão", ou seja, substituindo inteiramente um espaço reservado por texto de outro arquivo.

Se estou entendendo corretamente, a diferença entre "referenciamento" e "inclusão"/"transclusão" é simplesmente para _renderização_, digamos em html ou pdf. Para o analisador, não importa se um ativo (por exemplo) é referenciado ou transcluído, o mesmo AST resulta. Isso é correto?

1. Acho que uma boa sintaxe para ativos referenciados seria: ou = conforme discutido
2. Eu acho que uma boa sintaxe para transclusão seria {{ }} como usado por multi markdown.

Por que ter os dois em vez de apenas um método? Existe algum benefício para distinguir sintaticamente entre esses dois? Pessoalmente, prefiro o número um, pois ainda é renderizado como você pode seguir em um Markdown simples?

Acho que quando você diz "inclusão" está se referindo ao que quero dizer quando digo "transclusão", ou seja, substituindo inteiramente um espaço reservado por texto de outro arquivo.

Concordo, tentarei usar a transclusão a partir de agora. Obrigado!

Se estou entendendo corretamente, a diferença entre "referenciamento" e "inclusão"/"transclusão" é simplesmente para renderização

Na verdade. Na minha opinião, referir (criar uma referência) deve realmente apenas adicionar um link para a saída (AST) e deixar o resto nas ferramentas (https://github.com/apiaryio/api-blueprint/issues/20#issuecomment-26766374 )

Translcusion deve instruir o analisador (ou pré-processador) para puxar o conteúdo em...

Apenas uma atualização aqui: Isso é realmente planejado e muito necessário. Estamos trabalhando na ferramenta que torna isso possível. Enquanto isso, se você não confia no editor online Apiary, pode usar algo como https://gist.github.com/danvine/11087404 ou outra abordagem semelhante (eu conheço pelo menos algumas ferramentas baseadas em gulp para isso).

Whiskey agora suporta a extensão .apib e torna a edição de grandes arquivos Markdown muito mais fácil com sua visualização de destaque: http://vimeo.com/album/3108294/video/110486733

http://9muses.se/erato/ e http://25.io/mou/ também suportam .apib se você quiser um aplicativo de desktop (para Mac)

Robert Crooks Diretor de Serviços de Aprendizagem
Brightcove, Inc.

Em 29 de dezembro de 2015, às 16h08, Kevin Ingersoll [email protected] escreveu:

Whisky agora suporta o .apib
extensão e torna a edição de grandes arquivos Markdown muito mais fácil com sua visualização de contorno: http://vimeo.com/album/3108294/video/110486733

—
Responda a este e-mail diretamente ou visualize-o no GitHub
.

Ei @bcls e @holic , obrigado por apontar esses editores!

Relacionado: https://github.com/apiaryio/api-blueprint/issues/20#issuecomment -77108398

Alguma decisão foi tomada pelos desenvolvedores principais sobre isso? Tem sido excelente desde 2013 e nenhuma resposta clara foi dada até agora, podemos traçar uma linha sobre isso, por favor?

Ei, @foxx , ainda não houve uma decisão clara sobre isso - estou inclinado para a sintaxe de transclusão introduzida no Hercule :

FORMAT: 1A

# Gist Fox API
Gist Fox API is a **pastes service** similar to [GitHub's Gist](http://gist.github.com).

# Group Gist

:[Gist](blueprint/gist.md)

:[Gists](blueprint/gists.md)

Com a exceção de

`````` markdown

• Modelo

+ Body

  ```
  :[](gist.json)
  ```

``````

Porque os blocos de código devem permanecer opacos para o analisador/pré-processador.

Também não acho que a transclusão deva funcionar em nenhum nível – os arquivos que estão sendo transcluídos devem ser planos válidos em si.

Quanto ao compromisso com isso - é bastante alto no roteiro de recursos - mas ainda não há ETA.

Eu apreciaria quaisquer comentários ou pensamentos sobre isso e também sobre a visibilidade do roteiro de recursos.

Obrigado!

A sintaxe de transclusão parece ser a melhor proposta até agora, é uma abordagem elegante e limpa, e melhor do que qualquer outra sugestão que vi até agora. Fwiw, +1 de mim.

Alguma novidade sobre isso?

abordagem com transclusão me parece boa, não vejo desvantagens para isso.

Por enquanto sugiro usar o Hercule e a sintaxe :[Gist](blueprint/gist.md) . Trabalhará para fazer o backport de volta para a especificação do API Blueprint e a cadeia de ferramentas do analisador

Alguma coisa foi feita para este problema? Eu também gostaria de dividir um arquivo apib maior em vários.
Obrigado!

Ei @adams-sarah infelizmente não do meu lado. Eu ainda endosso o uso do Hercule (https://github.com/jamesramsay/hercule), pois funciona muito bem – a única desvantagem é que você não poderá editar os vários arquivos no Apiary.io. Deixe-me saber se eu puder ajudar de alguma forma!

+1 para o uso de hercule https://github.com/jamesramsay/hercule
estamos usando-o há algum tempo e esperamos que ainda encontre o caminho para as especificações do apib

:+1: para a adição deste recurso.

Também apoio uma única metodologia TOC/índice. A transclusão é um pouco flexível demais e não foi dimensionada em grandes documentos baseados em wiki na minha experiência anterior.

Definitivamente, teremos que inserir isso no próprio analisador para oferecer suporte ao mapa de origem.

Enquanto isso, preparamos um exemplo real para mostrar como usar o Hercule – https://github.com/apiaryio/api.apiblueprint.org

@zdne em nosso uso de json-schema (via interagent/prmd) nós o dividimos ao longo de linhas de recursos e basicamente aplicamos uma estrutura de diretório específica para implicar inclusões (mais ou menos ele cria um esquema de nível superior que tem todas as coisas no diretório como subesquemas, então ele muda os níveis das coisas). Obviamente, isso é bastante especializado no que estávamos fazendo e não é particularmente apropriado no seu caso, mas queremos compartilhar nossa experiência. Comparado a isso, acho que a transclusão parece muito mais elegante/flexível, mas definitivamente seria bom ter também alguns meios diretos de ter um TOC/índice consolidado. Talvez seja semelhante ao que fizemos, ou seja, você cria um uber blueprint para servir como esse índice e depois transclui/referencia os sub-blueprints dentro dele. Eu posso ver isso acontecendo automaticamente como sendo legal, mas também como sendo estranho se não acontecer de fazer exatamente o que você quer. De qualquer forma, muito longe de dizer que ficaria feliz em discutir/compartilhar minhas experiências se isso for útil.

Qual é o status desse recurso?
Estamos usando o plano Pro no Apiary.io e precisamos desse recurso

@DavidBM Eu tive o mesmo problema. como eu contornei isso é ter dois documentos apiary.apib .

Não compilado

apiary-source.apib - uma fonte não compilada que usa o recurso Incluir

FORMAT: 1A
HOST: https://api.example.com

# Hello World

<!-- include(blueprint/posts.apib) -->

Compilar

Você pode simplesmente executar:

aglio --input apiary-source.apib --compile --output apiary.apib

Seu apiary.apib agora deve incluir o conteúdo de blueprint/posts.apib dentro.

Olá, obrigado! Sim, mas você não pode editar os documentos em apiary.io

Já tínhamos a solução customizada com o Hercule, mas o objetivo de pagar o apiário pro para nós é deixar os gerentes de produto atualizarem a documentação sem entrar no git. Receio que isso seja um bloqueio completo para nós e cancelaremos o contrato com a Apiary se isso não for resolvido.

Eu não esperaria que isso estivesse neste estado depois de ter Hercule e outras ferramentas por tanto tempo disponíveis.

Isso é muito decepcionante :(

Olá a todos, desculpe por chegar aqui tarde e reabrir e cavar coisas antigas. Se este não for o lugar certo por favor me perdoe. Mas, fazendo uma pesquisa para desenvolver mocks de plantas, encontrei essa discussão e isso é o mais próximo que pude encontrar até agora.

Estou lutando para dividir minhas respostas por modelo :(. Não é possível referenciar um modelo em uma pasta diferente?
Eu gostaria de ter dentro da minha pasta blueprints todas as minhas solicitações e, por exemplo, em uma pasta de modelos separada todos os meus modelos de entidades (MSON/MD/JSON/qualquer arquivo, aquele cujo ajuste) para reutilizá-los em diferentes respostas facilmente. Alguém tem sucesso fazendo isso?

Seria muito bom se esse problema recebesse alguma atenção. Temos 26.000 linhas em nosso API Blueprint e isso torna incrivelmente difícil de gerenciar

Estamos implementando o teste de contrato usando Dredd e estamos usando Aglio, mas seria ótimo se isso fosse adicionado para que não tivéssemos que

Uma das razões é que estamos iterando muito no design :) Quando este problema foi aberto, não havia MSON e ainda estamos divididos em transclusões versus referências.

Mas para o registro, quais são suas necessidades lá? É apenas gerenciamento de vários arquivos e compilação de um único documento como resultado ou você também fala sobre reutilização de modelos e compartilhamento de bits e peças em vários documentos de descrição de API?

Uma das razões é que estamos iterando muito no design :) Quando este problema foi aberto, não havia MSON e ainda estamos divididos em transclusões versus referências.

Mas para o registro, quais são suas necessidades lá? É apenas gerenciamento de vários arquivos e compilação de um único documento como resultado ou você também fala sobre reutilização de modelos e compartilhamento de bits e peças em vários documentos de descrição de API?

Temos uma resposta padrão que vem de vários de nossos endpoints. gostaríamos de poder defini-lo em um único lugar, perto da biblioteca que o abriga, e depois importá-lo para onde precisarmos responder com ele.