Api-blueprint: 동일한 리소스에서 동일한 HTTP 동사의 여러 작업이 필요합니다(그러나 요청 내용 유형이 다름).

업데이트: 한 가지 응답만 언급하면 ​​이 작업을 수행할 수 있습니다.

FORMAT: 1A
# multiple posts?
## Try to make two posts [/v1/whatever]
### POST
+ Request JSON (application/json)
        { nil: nil }
+ Request DNS (text/dns)
        whatever
+ Response 204

그러나 임베디드 모드에서는 올바르게 표시되지 않습니다(하나의 요청 유형만 표시). 편집기 내의 미리보기 및 문서 보기가 좋습니다.

@jrep

이것은 현재 Apiary 내장(디자인)에서 부족한 것 같습니다. 이 문제에 대해 @apiaryio 팀에

@jrep 는 다중 응답을 지원하기 위한 요청(embed의 제한 옆에 있음)입니까?

그렇다면 다음이 이미 유효해야 합니다.

FORMAT: 1A

## Try to make two posts [/v1/whatever]

### POST

+ Request JSON (application/json)

        JSON

+ Response 200 (application/json)

        JSON       

+ Request DNS (text/dns)

        whatever

+ Response 200 (text/dns)

        whatever

귀하의 예는 여러 요청을 보여주지만 하나의 응답 만 보여줍니다. 내 예와 같습니다. 네, 문법적으로는 유효하지만 표현해야 할 것을 표현할 수 없습니다.

예: 여기에서 필요한 것은 각 요청에 대해 다른 "응답 200"을 표시하는 것입니다. 응답 내용 유형은 요청 내용 유형과 일치하지만(따라서 두 개의 요청 내용 유형은 두 개의 응답 내용 유형을 의미함) 두 응답의 정보도 정확히 동일하지 않습니다.

레거시 형식을 사용하여 하나의 요청과 해당 응답을 정의한 다음 다음 요청/응답 쌍을 정의했습니다. 그것은 새로운 형식의 구문 오류이며 이것을 말할 유효한 방법이 없는 것 같습니다.

업데이트: 죄송합니다. 충분히 자세히 보지 못했습니다. 귀하의 예는 두 가지 응답과 명명된 요청의 사용이라는 두 가지 면에서 나와 다릅니다. 지금 시도 중입니다.

@jrep

나는 당신이 그것을 어떻게 의미하는지 확실하지 않습니다. 레거시 청사진의 일부를 여기에 제출해 주시겠습니까?

Github 티켓으로 텍스트를 첨부할 수 없습니다. https://dev-staging.akamai.com/api/luna/config-dns/blueprint.apib 에서 레거시 청사진을 얻을 수 있습니다.

알았어요

POST /v1/zones/{zone}
> Content-Type: application/json
... some data ...
< 204
< Location: /v1/zones/example.com

POST /v1/zones/{zone}
> Content-Type: text/dns
... some other data ...
< 204
< Location: /v1/zones/example.com

나는 이것을 다음과 같이 표현하는 것이 근본적으로 괜찮다고 생각한다.

## Zone [/v1/zones/{zone}]

### Create [POST]

+ Request Create with JSON (application/json)

        { ... json data ... }

+ Request Create with DNS (text/dns)

        ... dns data ...

+ Response 204
    + Headers

            Location: /v1/zones/example.com

http://docs.multirequest.apiary.io

이것은 고전적인 내용 협상의 예입니다. 응답에 본문이 없고 OK(및 링크)만 표시되는 동안 다양한 표현에서 리소스를 만듭니다.

이에 대한 내용 협상 상대는 다음과 같습니다.

### Retrieve [GET]

+ Request Rerieve JSON representation
    + Headers

            Accept: application/json

+ Response 200 (application/json)

        { ... json data ... }

+ Request Rerieve DNS representation
    + Headers

            Accept: text/dns

+ Response 200 (text/dns)

        ... dns data ...

콘텐츠 유형은 다르지만 의미가 동일한(리소스 생성) 여러 요청에 대해 본문이 없는 하나의 응답이 좋은 디자인이라고 생각합니다. 그러나 https://github.com/apiaryio/snowcrash/issues/53 의 구현으로 이 제한(동일한 상태 및 콘텐츠 유형의 여러 응답이 있는 경우 경고)을 해제하고 싶습니다.

@jrep 이 문제는 https://github.com/apiaryio/snowcrash/issues/53 (Snow Crash v0.10.0)에서 해결되었으므로 종료합니다. 필요한 경우 댓글을 달고 다시 엽니다.

끝점에는 여러 트랜잭션 예제가 있을 수 있지만 apiaryio/snowcrash#53 에서 볼 수 있듯이 Apiary에서는 매우 깔끔하게 렌더링되지 않습니다.

다음 예를 들어 ...

사양에 따라 다양한 시나리오(예: 새로 고침에서 액세스 토큰 가져오기 또는 암호에서 토큰 생성 등)를 처리하는 /oauth2/authorize 가 있습니다. API 문서에서 이러한 작업을 단일 작업으로 병합하는 것은 독자가 이해하기 매우 어렵습니다. 대신 사이드 메뉴에서 "액세스 토큰 새로 고침" 및 "사용자 인증"과 같은 여러 엔드포인트를 사용하는 것이 더 쉽습니다. 그러나 동일한 메소드/URL 조합을 두 번 지정할 수 없기 때문에 불가능합니다.

이것은 API 사양이 개발자에게 특정 접근 방식을 사용하도록 강요하고 위와 같은 경우 일반적인 디자인 패턴에 맞지 않는 경우의 대표적인 예입니다.

잘못된 구문 강조 표시가 보입니다. Body 색상을 참조하십시오.