Api-blueprint: 그룹 내에서 둘 이상의 섹션 설정

@spark-ftw 불행히도 첫 번째 제목 Authentication 은 Print 리소스 그룹에 대한 설명에 첨부되었습니다. 설명은 리소스 제목 바로 아래에 표시되고 모든 리소스는 아래에 나열됩니다.

다음과 같이 다른 리소스 그룹을 그룹화하기 위해 이것을 약간 리팩토링하는 것이 좋습니다.

• 인증 그룹
  
  
  
  • 사용자 리소스 수집
  
  
  • 모든 사용자 나열
  
  
  • 새 사용자 계정 등록
  
  
• 인쇄 그룹
  
  
  
  • ...
  
  

첨부된 이미지에서 볼 수 있듯이 이미 그룹이 있습니다. "인쇄 그룹"이고 "인증" 및 "문서 인쇄"는 "인쇄 그룹"의 자식이므로 귀하의 솔루션이 저에게 적합하지 않습니다. 다른 생각이 있습니까?

감사

@spark-ftw @kylef가 의미하는 바는 정확합니다. 리소스( User Collection )를 이미 설명한 후에는 리소스 그룹( Group Print ) 내에서 임의의 마크다운 설명을 가질 수 없습니다.

다음과 같이 할 수 있습니다. ( @kylef가 제안한 것입니다).

# Group Authentication

## Authentication
Resource related to user auth

## User collection [/users]

### List all users [GET]
+ Response 200 (application/json)

            {}

### Register new user account [POST]
+ Request (application/json)

            {}

+ Response 201

            {}

# Group Print

## Print docs
Resource related to prints

## Print collection [/print]

### List all users [GET]
+ Response 200 (application/json)

            {}

### Register new user account [POST]
+ Request (application/json)

            {}

+ Response 201

            {}

편집 : 작은 오류를 수정한 후 주석을 업데이트했습니다.

다음과 같이 각 섹션 안에 여러 섹션이 필요하기 때문에 이것은 도움이 되지 않습니다.

• 섹션 인쇄

-- 인증 그룹

--- 사용자 컬렉션

--- 인증 수집

-- 문서 그룹

--- 문서 컬렉션 인쇄

--- 문서 컬렉션 저장

• 드라이브 섹션

-- 인증 그룹

--- 사용자 컬렉션

--- 인증 수집

-- 문서 그룹

--- 문서 컬렉션 인쇄

--- 문서 컬렉션 저장

...

감사

어떤 아이디어?

@spark-ftw 아래 코드에 !comments 를 추가했습니다. TL;DR 귀하의 표제 ##인증은 자원 설명의 일부가 아니라 그룹 설명의 일부입니다. 그룹에서 첫 번째 끝점을 정의하면 그룹 설명을 종료하고 리소스 끝점으로 시작했습니다.

FORMAT: 1A
HOST: https://sample

# sampleapi
Sample API

! group definition starts here with name, and description following
# Group Print
Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum Lorem Ipsum 

## Authentication <--- part of description above
Resource related to user auth <--- part of description above

! First endpoint definition starts here, group description ends here.
## User collection [/users]
### List all users [GET]
+ Response 200 (application/json)
        [...]

### Register new user account [POST]
+ Request (application/json)
            { ... }
+ Response 201
    + Headers
            Location: https://sample

## Print docs <-- this is not another endpoint / resource definition, but a description instead...
Resource related to prints <-- this is not another endpoint / resource definition, but a description instead...

! another resource endpoint is defined below, that is ok.
## Print collection [/print]
### List all users [GET]
+ Response 200 (application/json)
    [...]

좋아, 어떻게 내가 원하는 구조를 얻을 수 있습니까?

@spark-ftw 트리 구조를 고집하면 원하는 제목을 가질 수 없습니다. 다음과 같이 여러 그룹을 계속 사용할 수 있습니다.

Group Print Authentication
  - User Collection
    - List all
    - Register new...
Group Print Docs
Group Drive Authentication
Group Drive Docs
...

죄송하지만 더 많은 그룹을 사용하는 다른 솔루션이 없습니다. 그러나 Apiary의 문서 탐색에서 이러한 그룹을 사용하기 때문에 이점이 있습니다. 따라서 윈-윈 솔루션입니다.

내 요청을 다시 참조하십시오.

- 인쇄 섹션

-- 인증 그룹

--- 사용자 컬렉션

--- 인증 수집

-- 문서 그룹

--- 문서 컬렉션 인쇄

--- 문서 컬렉션 저장

드라이브 섹션

-- 인증 그룹

--- 사용자 컬렉션

--- 인증 수집

-- 문서 그룹

--- 문서 컬렉션 인쇄

--- 문서 컬렉션 저장

인쇄 외에 드라이브 제품도 필요합니다. 이것은 다른 것입니다(따라서 다른 계층 수준이 필요함)

그건 그렇고, 마크 다운은 이것을 지원하지만 양봉장 만 구문 분석에 문제가 있습니다 ...

@spark-ftw Apiary에 문제가 있는 것이 아닙니다. Resource Endpoints 사이에 설명이 허용되지 않는 것입니다. Apiary Editor에서 Warnings/Issues를 살펴보면 거기에 Warning이 표시됩니다. 사양에 따르면 https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md#def -section-structure - Group 섹션에는 다음 부분이 포함됩니다. 그룹 이름 , 그룹 설명, 그룹 리소스. 중간에 다른 설명으로 아무것도 없습니다.

Markdown과 API Blueprint를 비교하는 경우 - 대신 선형, 비 트리 구조로 끝납니다.

@spark-ftw Group 키워드는 새로운 Section 시작을 나타내는 데 사용됩니다.
API Blueprint는 3단계 중첩을 전혀 지원하지 않습니다. 위의 설명에 링크된 사양 파일을 참조하세요.

그래서 내 문제에 대한 해결책이 없습니까?