Api-blueprint: 모듈성

많은 수의 API가 있고 회사의 다른 그룹이 제어할 수 있는 상황의 경우 이것은 절대적인 신의 선물이 될 것입니다.

@rurounijones 설명을 위해 이 기능은 "하나의 API 설명을 여러 파일로 분할할 수 있음"을 의미합니다.

누구든지 이것에 대해 어떤 생각이 있습니까? Drafter https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28538342에 대한 내 이전 의견에 따라

옵션은 청사진 상단에 일부 포함/요구 기능을 추가하거나 디렉토리에서 모든 청사진을 가져와서 함께 연결하는 것입니다.

생각?

연결은 더 간단하지만 내가 원하는 대로 require를 사용하는 것이 더 쉬울 것이라고 생각하고 그 다음에 다른 것을 추가합니다.

이것은 특허에 정의된 것처럼 파일의 내용을 맹목적으로 인라인하는 것입니까, 아니면 파일의 내용에 어떤 종류의 제한이 있습니까(예: 고유한 yaml 헤더를 가질 수 있습니까? 상위 yaml과의 충돌?) 나는 제한이 없는 것이 더 나을 것이라는 느낌을 받았지만 그것을 꺼낼 것이라고 생각했습니다.

@zdne

먼저, 간단한 파일 연결을 사용하여 Grunt로 이미 이를 관리하기 위한 기초 시스템이 있습니다. 우리의 청사진은 관리할 수 없게 되었고, 이것은 파일로 분할하는 빠르고 더러운 방법이었습니다(참고로, 파일 시스템 순서에 따라 연결되어 있기 때문에 임의적으로 많은 파일이 있음). 여기 에 짧은 설명과 함께 내 Gruntfile을 게시했습니다.

연결이 너무 간단하여 스스로 굴릴 수 있다는 점을 감안할 때 "공식" 도구가 더 강력해야 한다는 것이 합리적입니다. 다른 시스템에서 이 문제를 처리하는 방법에 대한 연구를 수행하면서 이에 대해 더 많이 생각하고 있습니다.

1. 포함/요구
   
   
   
   • 포함은 파일 상단에서 수행되고 파일의 일부는 파일 내에서 참조됩니다. 나는 이것이 현재의 [Model Reference][] 구문보다 더 강력한 참조 시스템이 필요하다고 생각합니다. 이상적으로 포함된 파일의 모든 노드는 주소를 지정할 수 있으므로 [github.Users.'Create A User'][] 또는 [github][POST /users] 등과 같은 노드가 있을 수 있습니다. ( = 와 같은 접두사가 필요할 수도 있습니다.) name 또는 url+method 외에 AST의 특정 노드를 참조하는 더 좋은 방법이 있습니까?
   
   
   • 노드 내용을 역참조하는 좋은 방법이 있다는 점을 감안할 때 추가 비용 없이 많은 추가 기능과 함께 제공되는 C 전처리기로 이를 수행할 수 있습니다.
   
   
2. 템플릿 시스템/트랜스루젼
   
   
   
   • 비 마크다운 - 템플릿은 별도의 템플릿 언어로 작성되므로 템플릿 파일은 snowcrash로 구문 분석할 수 없습니다. 이와 같은 것의 예로는 grunt-readme 가 있습니다. 이것은 청사진 파일을 템플릿화하기 위해 즉시 사용할 수 있는 것처럼 보입니다.
   
   
   • 마크다운 - 이것은 초안 문제에서 논의한 =[]() 또는 :[]() 구문과 같습니다. 여전히 유효한 마크다운이며 snowcrash로 구문 분석할 수 있습니다.
   
   
3. 둘 다
   
   
   
   • 참조 노드( [github]['Create A User'] ) 및 직접 변환( :[/github.md](/github.md) )에 대한 구문을 정의하면 둘 다 쉽게 가질 수 있을 것 같습니다. 아마도 :[]() 와 같은 일반 구문이 있을 수 있으며 파서는 노드인지 파일 참조인지 결정합니다.
   
   

이에 대한 생각이 있습니까? 일부 옵션/도구가 누락되었습니까? 나는 transclusion 및 node 역참조를 위한 공통 구문을 사용하여 "both" 옵션을 선호하지만 아마도 그 정도일 것입니다.

연결이 스스로 굴리기가 너무 쉽다는 점을 감안할 때 "공식" 도구가 더 강력해야 한다는 것이 합리적입니다.

글쎄, 결국은 그럴 수도 있겠지만, 나는 그것을 지나치게 디자인하지 않고 구걸에서 간결하고 단순한 것을 롤아웃하고 싶습니다.

해결해야 할 현재 문제를 살펴보면 주로 다음과 같습니다.

1. 참조된(외부) 자산 - #20 및 https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071에서 논의됨
2. 청사진을 보다 관리하기 쉬운 논리적 부분으로 분할

분할을 위해 리소스 그룹 또는 리소스(예: 작업, 트랜잭션 예제 또는 요청 제외)만 고려합니다. 적어도 처음에는.

광고 1: _참조된 자산_이 #20의 제안에 의해 우아하게 처리되고 https://github.com/apiaryio/snowcrash/issues/57#issuecomment -28564071 논의될 것이라고 생각합니다.

광고 2: 나는 그것을 전혀 복잡하게 만들지 않을 것입니다. 내가 transclusion에 사용할 유일한 것은 [Some Text](path/to/blueprint/file.apib) 또는 [Some Text](path/to/blueprint/file.apib#resource-name) 와 같은 일반 마크다운 구문입니다. 포함을 위해 드래프터의 자산과 동일한 원칙을 따를 것입니다. 예를 들어 참조 전에 : 를 사용합니다. https://gist.github.com/zdne/8804418#aliens -question-aliens_question과 같은 것

나는 이것이 시작에 충분할 수 있다고 생각합니까?

나는 이것이 시작에 충분할 수 있다고 생각합니까?

동의. 나는 당신이 "자산"을 포함하는 것과 "리소스"/"리소스 그룹"을 포함하는 것을 구별하고 있다는 것을 이제야 깨달았습니다. 나는 그들 모두를 마음대로 포함시킬 "노드"로 생각하고있었습니다.

두 번째 요점에 대해서는 기존 MultiMarkdown 구문 을 참조하는 것이 유용할 것이라고 생각했습니다.

This is some text.

{{some_other_file.txt}}

Another paragraph

이것은 리소스를 포함하는 간단한 방법처럼 보입니까? (또는 실제로 임의의 텍스트/노드?)

따라서 내 의견을 명확히하기 위해 :

1. 참조된 자산에 대한 좋은 구문은 논의된 대로 :[]() 또는 =[]() 입니다.
2. transclusion에 대한 좋은 구문은 multimarkdown에서 사용되는 {{ }} 것입니다.

또한 일부 어휘를 명확히 하기 위해: "포함"이라고 하는 것은 제가 "transclusion"이라고 말할 때 의미하는 바, 즉 자리 표시자를 다른 파일의 텍스트로 완전히 대체하는 것을 말하는 것이라고 생각합니다.

내가 올바르게 이해하고 있다면 "참조"와 "포함"/"변환"의 차이점은 단순히 _렌더링_을 위한 것입니다. 파서에게 자산(예: 자산)이 참조되거나 제외되는지 여부는 중요하지 않으며 동일한 AST 결과가 나타납니다. 그 맞습니까?

1. 참조 자산에 대한 좋은 구문은 다음과 같습니다. 또는 = 논의된 대로
2. 나는 다중 마크다운에서 사용되는 {{ }} 트랜스클루전을 위한 좋은 구문이라고 생각합니다.

한 가지 방법 대신 두 가지 방법을 모두 사용해야 하는 이유는 무엇입니까? 이 둘을 구문적으로 구별하면 어떤 이점이 있습니까? 개인적으로 나는 1번을 선호합니다. 왜냐하면 그것은 여전히 ​​평범한 Markdown에서 따를 수 있기 때문입니다.

"포함"이라고 하면 제가 "트랜스클루젼"이라고 할 때 의미하는 바, 즉 자리 표시자를 다른 파일의 텍스트로 완전히 바꾸는 것을 의미한다고 생각합니다.

동의합니다. 이제부터 transclusion을 사용하려고 합니다. 감사 해요!

내가 올바르게 이해하고 있다면 "참조"와 "포함"/"변환"의 차이점은 단순히 렌더링을 위한 것입니다.

설마. 내 의견으로는 참조(참조 생성)는 실제로 출력(AST)에 대한 링크만 추가하고 나머지는 도구에 남겨 두어야 합니다(https://github.com/apiaryio/api-blueprint/issues/20#issuecomment-26766374 )

Translcusion은 파서(또는 전처리기)에 내용을 가져오도록 지시해야 합니다...

여기 업데이트: 이것은 실제로 계획되었고 많이 필요합니다. 우리는 이것을 가능하게 하는 도구를 연구하고 있습니다. 한편 Apiary 온라인 편집기에 의존하지 않는 경우 https://gist.github.com/danvine/11087404 또는 이와 유사한 다른 접근 방식을 사용할 수 있습니다.

Whisky는 이제 .apib 확장자를 지원하고 개요 보기를 통해 대용량 Markdown 파일을 훨씬 쉽게 편집할 수 있습니다. http://vimeo.com/album/3108294/video/110486733

http://9muses.se/erato/ 및 http://25.io/mou/ 는 데스크톱 앱(Mac용)을 원하는 경우 .apib도 지원합니다.

Robert Crooks 학습 서비스 이사
브라이트코브

2015년 12월 29일 오후 4시 8분에 Kevin Ingersoll [email protected] 이 다음과 같이 썼습니다.

Whisky는 이제 .apib를 지원합니다.
확장자 및 개요 보기로 대용량 Markdown 파일을 훨씬 쉽게 편집할 수 있습니다. http://vimeo.com/album/3108294/video/110486733

—
이 이메일에 직접 답장하거나 GitHub에서 확인하세요.
.

@bcls 와 @holic , 이 편집자들을 지적해 주셔서 감사합니다!

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

이에 대한 핵심 개발자의 결정이 있습니까? 2013년부터 뛰어난 성능을 보여 아직까지 명확한 답변이 없습니다. 이 부분에 대해 선을 그어봐도 될까요?

Hey @foxx 아직 이에 대한 명확한 결정이 없었습니다. 저는 Hercule 에 도입된 transclusion 구문에 기대고 있습니다.

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)

제외한

`````` 마크다운

• 모델

+ Body

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

``````

코드 블록은 파서/전처리기에 불투명하게 유지되어야 하기 때문입니다.

또한 저는 트랜스클루전이 어떤 수준에서도 작동해야 한다고 생각하지 않습니다. 트랜스클루드되는 파일은 유효한 청사진 자체여야 합니다.

이에 대한 약속은 기능 로드맵에서 상당히 높지만 ETA는 아직 없습니다.

이에 대한 의견이나 생각과 기능 로드맵 가시성에 대한 의견을 주시면 감사하겠습니다.

감사 해요!

transclusion 구문은 지금까지 최고의 제안처럼 보이며 우아하고 깔끔한 접근 방식이며 지금까지 내가 본 다른 어떤 제안보다 좋습니다. Fwiw, 나에게서 +1.

이것에 대한 소식이 있습니까?

트랜스클루전을 사용한 접근 방식은 나에게 좋은 것 같지만 단점은 없습니다.

당분간은 Hercule 및 :[Gist](blueprint/gist.md) 구문을 사용하는 것이 좋습니다. API Blueprint 사양 및 파서 도구 체인으로 다시 백포팅하기 위해 노력할 것입니다.

이 문제에 대해 수행된 작업이 있습니까? 또한 더 큰 apib 파일을 여러 개로 나누고 싶습니다.
감사 해요!

안녕하세요 @adams-sarah는 불행히도 제 편이 아닙니다. 나는 여전히 Hercule(https://github.com/jamesramsay/hercule)의 사용을 지지합니다. 꽤 잘 작동하기 때문입니다. 유일한 단점은 Apiary.io에서 여러 파일을 편집할 수 없다는 것입니다. 내가 어떻게든 도울 수 있는지 알려주세요!

+1 hercule https://github.com/jamesramsay/hercule 사용
우리는 그것을 잠시 동안 사용해 왔으며 여전히 apib 사양에 들어갈 수 있기를 바랍니다.

:+1: 이 기능을 추가합니다.

또한 단일 목차/색인 방법론을 지원합니다. Transclusion은 약간 너무 유연하며 내 과거 경험에서 대규모 Wiki 기반 문서에서 확장되지 않았습니다.

소스 맵을 지원하기 위해 이것을 파서 자체에 구워야 합니다.

그동안 Hercule 사용법을 보여주는 실제 예를 준비했습니다 – https://github.com/apiaryio/api.apiblueprint.org

@zdne json-schema(interagent/prmd를 통해) 사용에서 우리는 리소스 라인을 따라 그것을 분할하고 기본적으로 포함을 암시하기 위해 특정 디렉토리 구조를 시행합니다(어느 정도 디렉토리에 있는 모든 것을 포함하는 최상위 스키마를 빌드합니다. 하위 스키마, 그래서 그것은 사물의 수준을 변경합니다). 이것은 분명히 우리가 하고 있는 일에 매우 전문적이며 귀하의 경우에는 특히 적절하지 않지만 우리의 경험을 공유하고 싶었습니다. 그것에 비해, 내 생각에 transclusion은 훨씬 더 우아하고 유연해 보이지만 통합된 TOC/index를 갖는 몇 가지 간단한 수단도 분명히 있으면 좋을 것입니다. 우리가 한 것과 비슷할 수도 있습니다. 즉, 이 인덱스 역할을 할 uber 청사진을 만든 다음 그 안에 하위 청사진을 삽입/참조합니다. 나는 그것이 자동으로 일어나는 좋은 일이지만 원하는 대로 되지 않으면 어색한 것으로 볼 수 있습니다. 어쨌든, 그것이 도움이된다면 더 많은 이야기를 나누거나 내 경험을 공유하게되어 기쁩니다.

이 기능의 상태는 무엇입니까?
우리는 Apiary.io에서 Pro 플랜을 사용하고 있으며 이 기능이 필요합니다.

@DavidBM 저도 같은 문제가 있었습니다. 이 문제를 해결한 방법은 두 개의 apiary.apib 문서가 있는 것입니다.

컴파일되지 않음

apiary-source.apib - 포함 기능 을 사용하는 컴파일되지 않은 소스

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

# Hello World

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

엮다

다음을 간단히 실행할 수 있습니다.

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

이제 apiary.apib 에 blueprint/posts.apib 의 내용이 포함되어야 합니다.

안녕하세요, 감사합니다! 예, 하지만 apiary.io에서 문서를 편집할 수 없습니다.

우리는 이미 Hercule과 함께 맞춤형 솔루션을 가지고 있었지만 우리를 위해 양봉장 프로를 지불하는 요점은 제품 관리자가 git에 입력하지 않고 문서를 업데이트할 수 있도록 하는 것입니다. 이것이 우리에게 완전히 방해가 될까봐 두렵고 이것이 해결되지 않으면 양봉장과의 계약을 취소할 것입니다.

Hercule 및 기타 도구를 오랫동안 사용할 수 있게 된 후 이 상태가 될 것이라고는 예상하지 못했습니다.

이것은 매우 실망스럽습니다 :(

안녕하세요 여러분, 늦게 와서 오래된 물건을 다시 열고 파서 죄송합니다. 이것이 올바른 장소가 아니라면 저를 용서하십시오. 그러나 청사진 모형을 개발하기 위한 연구를 하면서 이 토론을 찾았고 이것이 지금까지 내가 찾을 수 있는 가장 가까운 것입니다.

내 응답을 모델별로 분할하는 데 어려움을 겪고 있습니다. (. 모델을 다른 폴더로 참조하는 것이 가능하지 않습니까?
내 청사진 폴더 안에 내 모든 요청이 있고, 예를 들어 분리된 모델 폴더에 내 모든 엔티티 모델(MSON/MD/JSON/무엇이든 적합한 파일)을 넣어 다른 응답으로 쉽게 재사용하고 싶습니다. 누구든지이 작업을 성공적으로 수행 했습니까?

이 문제가 약간의 관심을 끌면 정말 좋을 것입니다. API Blueprint에는 26000줄이 있으며 관리하기가 매우 어렵습니다.

우리는 Dredd를 사용하여 계약 테스트를 구현하고 Aglio를 사용하고 있지만 이것이 추가되어

그 이유 중 하나는 우리가 디자인을 많이 반복하고 있기 때문입니다. :) 이 문제가 공개되었을 때 MSON이 없었고 우리는 여전히 트랜스클루전과 참조에 대해 고민하고 있습니다.

그러나 기록을 위해 거기에 무엇이 필요합니까? 결과적으로 다중 파일 관리 및 단일 문서 컴파일입니까, 아니면 여러 API 설명 문서에서 모델의 재사용 가능성과 공유 비트 및 조각에 대해서도 이야기합니까?

그 이유 중 하나는 우리가 디자인을 많이 반복하고 있기 때문입니다. :) 이 문제가 공개되었을 때 MSON이 없었고 우리는 여전히 트랜스클루전과 참조에 대해 고민하고 있습니다.

그러나 기록을 위해 거기에 무엇이 필요합니까? 결과적으로 다중 파일 관리 및 단일 문서 컴파일입니까, 아니면 여러 API 설명 문서에서 모델의 재사용 가능성과 공유 비트 및 조각에 대해서도 이야기합니까?

우리는 우리의 끝점에서 오는 표준 응답을 가지고 있습니다. 우리는 그것을 보관하고 있는 라이브러리 근처의 단일 장소에서 정의할 수 있기를 원하고, 그리고 나서 우리가 그것에 응답해야 할 때마다 그것을 가져올 수 있기를 바랍니다.