Api-blueprint: Modularidad

Para aquellas situaciones en las que hay una gran cantidad de API, posiblemente bajo el control de diferentes grupos en una empresa, esto sería una bendición absoluta.

@rurounijones solo para aclarar que esta función está destinada a "Poder dividir una descripción de API en varios archivos".

¿Alguien tiene alguna idea sobre esto? Según mi comentario anterior sobre Drafter https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28538342

Las opciones son agregar alguna instalación de inclusión/requerimiento en la parte superior del plano o simplemente buscar todos los planos de un directorio y concatenarlos juntos.

¿Pensamientos?

La concatenación es más simple, pero creo que require sería más fácil de usar, ya que es posible que desee requerir, luego agregue algo más después.

¿Será esto simplemente uniendo ciegamente el contenido del archivo como si estuviera definido en la patente, o habrá algún tipo de restricción en el contenido del archivo (por ejemplo, pueden tener su propio encabezado yaml? ¿Conflictos con el yaml padre?) Tengo la sensación de que ninguna restricción sería mejor, pero pensé en mencionarlo.

@zdne

En primer lugar, ya tengo un sistema rudimentario para administrar esto con Grunt, usando una concatenación simple de archivos. Nuestro modelo se estaba volviendo inmanejable, y esta era una forma rápida y sucia de dividirlo en archivos (de nota, muchos archivos arbitrariamente, porque están concatenados por el orden del sistema de archivos). Publiqué mi Gruntfile con una breve explicación aquí .

Dado que la concatenación es tan simple de hacer usted mismo, tiene sentido para mí que una herramienta "oficial" sea más poderosa. He estado pensando más en esto, tratando de investigar un poco sobre cómo otros sistemas manejan esto.

1. Incluir/Requerir
   
   
   
   • Las inclusiones se harían en la parte superior de un archivo y se haría referencia a partes del archivo dentro. Creo que esto requiere un sistema de referencia más robusto que la sintaxis actual [Model Reference][] . Idealmente, cualquier nodo en el archivo incluido sería direccionable, por lo que uno podría tener algo como [github.Users.'Create A User'][] o [github][POST /users] o algo así. (También podría necesitar un prefijo como = ). ¿Hay alguna forma mejor de hacer referencia a un nodo específico en el AST que no sea nombre o url+método?
   
   
   • Dado que tiene una buena manera de desreferenciar el contenido de los nodos, esto podría hacerse con el preprocesador C , que vendría con muchas características adicionales sin costo adicional.
   
   
2. Sistema de plantillas/Transclusión
   
   
   
   • Sin rebajas: la plantilla se escribiría en un lenguaje de plantillas independiente, por lo que Snowcrash no podría analizar un archivo de plantilla. Un ejemplo de algo como esto es grunt-readme , que parece que podría funcionar de inmediato para crear una plantilla de archivo de plano.
   
   
   • Markdown: esto sería algo así como la sintaxis =[]() o :[]() que discutimos sobre el problema del redactor. Seguiría siendo una rebaja válida y analizable por snowcrash.
   
   
3. Ambas cosas
   
   
   
   • Dado que define una sintaxis para los nodos de referencia ( [github]['Create A User'] ) y la transclusión directa ( :[/github.md](/github.md) ), parece que fácilmente podría tener ambos. Quizás podrían tener la misma sintaxis general como :[]() y el analizador determina si es un nodo o una referencia de archivo.
   
   

Tiene alguna idea sobre esto? ¿Me estoy perdiendo algunas opciones/herramientas? Me inclino por la opción "ambos" con una sintaxis común para la transclusión y la desreferenciación de nodos, pero tal vez eso sea demasiado.

Dado que la concatenación es tan simple de hacer usted mismo, tiene sentido que una herramienta "oficial" sea más poderosa.

Bueno, eventualmente, tal vez sí, pero me gustaría no diseñarlo en exceso y lanzar algo sencillo y simple al principio.

En cuanto a los problemas actuales, los problemas que deben abordarse son principalmente:

1. Recursos referenciados (externos): n.° 20 y como se describe en https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071
2. Dividir el proyecto en partes lógicas más manejables

Con el fin de dividir, consideraría solo un grupo de recursos o un recurso (por ejemplo, no una acción, un ejemplo de transacción o una solicitud). Al menos en los comienzos.

Anuncio 1: Siento que los _activos referenciados_ serían abordados elegantemente por la propuesta en el n.° 20 y discutidos https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071

Anuncio 2: No lo complicaría en absoluto. Lo único que usaría para la transclusión es la sintaxis regular de rebajas, por ejemplo [Some Text](path/to/blueprint/file.apib) o [Some Text](path/to/blueprint/file.apib#resource-name) . Para la inclusión, seguiría el mismo principio que con los activos en el redactor, por ejemplo, use : antes de la referencia. Algo como https://gist.github.com/zdne/8804418#aliens -question-aliens_question

Creo que esto podría ser suficiente para el comienzo?

Creo que esto podría ser suficiente para el comienzo?

Acordado. Ahora me doy cuenta de que está haciendo una distinción entre incluir "activos" e incluir "recursos"/"grupos de recursos". Había estado pensando en todos ellos como "nodos" para ser incluidos a voluntad.

Para el segundo punto, pensé que sería útil hacer referencia a la sintaxis MultiMarkdown existente para la transclusión:

This is some text.

{{some_other_file.txt}}

Another paragraph

¿Parece una forma sencilla de incluir recursos? (¿o de hecho, texto/nodos arbitrarios?)

Así que para aclarar mi opinión:

1. Creo que una buena sintaxis para los activos a los que se hace referencia sería :[]() o =[]() como se explicó
2. Creo que una buena sintaxis para la transclusión sería {{ }} como la usa multimarkdown.

Y también para aclarar algo de vocabulario: _creo_ que cuando dices "inclusión" te refieres a lo que quiero decir cuando digo "transclusión", es decir, reemplazar completamente un marcador de posición con texto de otro archivo.

Si lo entiendo correctamente, la diferencia entre "referenciar" e "inclusión"/"transclusión" es simplemente para _renderizar_, digamos en html o pdf. Para el analizador, no importa si se hace referencia o se transcluye un activo (por ejemplo), se obtiene el mismo AST. ¿Es eso correcto?

1. Creo que una buena sintaxis para los activos referenciados sería: o = como se discutió
2. Creo que una buena sintaxis para la transclusión sería {{ }} tal como se usa en la reducción múltiple.

¿Por qué tener ambos en lugar de un solo método? ¿Hay algún beneficio para distinguir sintácticamente entre esos dos? Personalmente, prefiero el número uno, ya que todavía se muestra como un Markdown simple.

Creo que cuando dice "inclusión" se refiere a lo que quiero decir cuando digo "transclusión", es decir, reemplazar completamente un marcador de posición con texto de otro archivo.

De acuerdo, intentaré usar la transclusión a partir de ahora. ¡Gracias!

Si entiendo correctamente, la diferencia entre "referenciar" e "inclusión"/"transclusión" es simplemente por el hecho de representar

Realmente no. En mi opinión, hacer referencia (crear una referencia) realmente solo debería agregar un enlace a la salida (AST) y dejar el resto en las herramientas (https://github.com/apiaryio/api-blueprint/issues/20#issuecomment-26766374 )

La translcusión debe instruir al analizador (o preprocesador) para extraer el contenido...

Solo una actualización aquí: de hecho, esto está planeado y es muy necesario. Estamos trabajando en la herramienta que lo hace posible. Mientras tanto, si no confía en el editor en línea Apiary, puede usar algo como https://gist.github.com/danvine/11087404 u otro enfoque similar (conozco al menos algunas herramientas basadas en gulp para esto).

Whisky ahora es compatible con la extensión .apib y facilita mucho la edición de archivos grandes de Markdown con su vista de esquema: http://vimeo.com/album/3108294/video/110486733

http://9muses.se/erato/ y http://25.io/mou/ también admiten .apib si desea una aplicación de escritorio (para Mac)

Robert CrooksDirector de Servicios de Aprendizaje
Brightcove, Inc.

El 29 de diciembre de 2015, a las 4:08 p. m., Kevin Ingersoll [email protected] escribió:

Whisky ahora es compatible con .apib
extensión y hace que la edición de archivos grandes de Markdown sea mucho más fácil con su vista de esquema: http://vimeo.com/album/3108294/video/110486733

—
Responda a este correo electrónico directamente o véalo en GitHub
.

Hola @bcls y @holic , ¡gracias por señalar estos editores!

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

¿Los desarrolladores principales han tomado alguna decisión al respecto? Ha estado pendiente desde 2013 y hasta ahora no se ha dado una respuesta clara, ¿podemos trazar una línea en esto, por favor?

Oye, @foxx , todavía no hubo una decisión clara sobre esto. Me inclino por la sintaxis de transclusión introducida en 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)

Con la excepción de

descuento ``````

• Modelo

+ Body

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

``````

Porque los bloques de código deben permanecer opacos para el analizador/preprocesador.

Además, no creo que la transclusión deba funcionar en ningún nivel: los archivos que se transcluyen deben ser planos válidos en sí mismos.

En cuanto al compromiso con esto, es bastante alto en la hoja de ruta de características, pero todavía no hay ETA.

Apreciaría cualquier comentario o pensamiento sobre esto y también sobre la visibilidad de la hoja de ruta de las funciones.

¡Gracias!

La sintaxis de transclusión parece la mejor propuesta hasta ahora, es un enfoque elegante y limpio, y mejor que cualquier otra sugerencia que haya visto hasta ahora. Vaya, +1 de mi parte.

¿Alguna noticia sobre esto?

El enfoque con transclusión me parece bueno, no le veo ninguna desventaja.

Por el momento sugiero usar Hercule y la sintaxis :[Gist](blueprint/gist.md) . Trabajará para volver a adaptarlo a la especificación API Blueprint y la cadena de herramientas del analizador.

¿Se ha hecho algo para este problema? También me gustaría dividir un archivo apib más grande en varios.
¡Gracias!

Hola, @adams-sarah, desafortunadamente no de mi parte. Todavía apoyo el uso de Hercule (https://github.com/jamesramsay/hercule) ya que funciona bastante bien; el único inconveniente es que no podrá editar los múltiples archivos en Apiary.io. ¡Déjame saber si puedo ayudar de alguna manera!

+1 al uso de hercule https://github.com/jamesramsay/hercule
lo hemos estado usando durante un tiempo y esperamos que aún encuentre su camino en las especificaciones de apib

:+1: por la adición de esta función.

También admito una sola metodología TOC/índice. La transclusión es un poco demasiado flexible y no se ha escalado en documentos grandes basados ​​en wiki en mi experiencia pasada.

Definitivamente tendremos que hornear esto en el analizador para admitir el mapa fuente.

Mientras tanto, hemos preparado un ejemplo real para mostrar cómo usar Hercule: https://github.com/apiaryio/api.apiblueprint.org

@zdne en nuestro uso de json-schema (a través de interagent/prmd) lo dividimos a lo largo de las líneas de recursos y básicamente aplicamos una estructura de directorio particular para implicar inclusiones (más o menos crea un esquema de nivel superior que tiene todas las cosas en el directorio como subesquemas, por lo que cambia los niveles de las cosas). Obviamente, esto está bastante especializado en lo que estábamos haciendo y no es particularmente apropiado en su caso, pero quería compartir nuestra experiencia. En comparación con eso, creo que la transclusión parece mucho más elegante/flexible, pero definitivamente sería bueno tener también algún medio sencillo de tener un TOC/índice consolidado. Sin embargo, tal vez eso sea similar a lo que hicimos, es decir, creas un súper plano para que sirva como este índice y luego transcluyes/referencias a los subplanos dentro de él. Puedo ver que eso sucede automáticamente como agradable, pero también como incómodo si no sucede exactamente lo que quieres. De todos modos, es una larga manera de decir que estaría feliz de discutir/compartir mis experiencias más a fondo si eso fuera útil.

¿Cuál es el estado de esta función?
Estamos usando el plan Pro en Apiary.io y necesitamos esta característica

@DavidBM Tuve el mismo problema. cómo solucioné esto es tener dos documentos apiary.apib .

sin compilar

apiary-source.apib : una fuente no compilada que utiliza la función Incluir

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

# Hello World

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

Compilar

Simplemente puede ejecutar:

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

Su apiary.apib ahora debe incluir el contenido de blueprint/posts.apib dentro.

¡Hola Gracias! Sí, pero entonces no puedes editar los documentos en apiary.io

Ya teníamos la solución personalizada con Hercule, pero el punto de pagar apiary pro para nosotros es permitir que los gerentes de producto actualicen la documentación sin ingresar a git. Me temo que esto es un bloqueo total para nosotros y cancelaremos el contrato con Apiary si esto no se soluciona.

No esperaría que esto estuviera en este estado después de tener Hércules y otras herramientas disponibles durante tanto tiempo.

Esto es muy, muy decepcionante :(

Hola a todos, lo siento por llegar tarde y reabrir y cavar cosas viejas. Si este no es el lugar correcto por favor perdóname. Pero, investigando para desarrollar simulacros de planos, encontré esta discusión y esto es lo más cercano que pude encontrar hasta ahora.

Me cuesta dividir mis respuestas por modelo :(. ¿No es posible referir un modelo a una carpeta diferente?
Me gustaría tener dentro de mi carpeta de blueprints todas mis solicitudes y, por ejemplo, en una carpeta de modelos separada, todos mis modelos de entidades (MSON/MD/JSON/cualquier archivo, cuyo ajuste) para reutilizarlos fácilmente en diferentes respuestas. ¿Alguien tiene éxito haciendo esto?

Sería realmente genial si este problema llamara la atención. Tenemos 26000 líneas en nuestro API Blueprint y lo hace increíblemente difícil de administrar

Estamos implementando pruebas de contratos usando Dredd y Aglio, pero sería genial si esto se agregara para no tener que hacerlo.

Una de las razones es que estamos iterando mucho en el diseño :) Cuando se abrió este problema, no había MSON y todavía estamos divididos entre transclusiones y referencias.

Pero para que conste, ¿cuáles son sus necesidades allí? ¿Se trata simplemente de la gestión de varios archivos y la compilación de un solo documento como resultado o también habla de la reutilización de modelos y el intercambio de fragmentos en varios documentos de descripción de API?

Una de las razones es que estamos iterando mucho en el diseño :) Cuando se abrió este problema, no había MSON y todavía estamos divididos entre transclusiones y referencias.

Pero para que conste, ¿cuáles son sus necesidades allí? ¿Se trata simplemente de la gestión de varios archivos y la compilación de un solo documento como resultado o también habla de la reutilización de modelos y el intercambio de fragmentos en varios documentos de descripción de API?

Tenemos una respuesta estándar que proviene de un montón de nuestros puntos finales. nos gustaría poder definir eso en un solo lugar, cerca de la biblioteca que lo alberga, y luego importarlo donde sea que necesitemos responder con él.