개발자센터 api 문서 예시 요청/응답 값 보여주기

[CirnoV]

작업 내용

• openapi.json 스키마에 정의되어 있는 example 프로퍼티로 예시 응답을 보여주는 ResExample 컴포넌트를 구현했습니다.
• Try 요청 초기값이 example 프로퍼티 값으로 설정되도록 했고, string 타입의 기본 값을 빈 문자열에서 파라미터 이름으로 변경했습니다.
• Parameter["type"]이 falsy일 경우에 Parameter["schema"]["type"] 값으로 타입이 결정되지 않고 object로 잘못 설정되는 버그를 수정했습니다.
• httpsnippet-lite 라이브러리를 사용해서 Try 요청을 다양한 코드 샘플로 보여주는 ReqSample 컴포넌트를 구현했습니다.
• Try 응답 결과를 보여주는 컴포넌트를 기본적으로 비활성화 하고, 요청을 실행했을 때 표시하도록 변경했습니다.

설명

• Example 섹션을 별도로 만들기 보다는, 기존에 사용하고 있던 Try 섹션에서 예시 파라미터 값을 보여주는 방향이 공간 효율적이고, 에디터로 수정할 수 있으면서 복사도 용이하기 때문에 DX면에서 더 좋다고 판단했습니다.
• 응답 결과를 보여주는 컴포넌트를 기본적으로 비활성화 한 이유는, 이렇게 하면 요청 에디터와 요청 샘플을 나란히 표시할 수 있고, 응답 결과 자체가 사용자가 실행 버튼을 누르는 Action이 있어야 생성되는 데이터이기 때문에 굳이 N/A 형태로 표시할 이유가 없다고 판단했기 때문입니다.
• string 타입의 기본값을 파라미터 이름으로 설정한 이유는 요청 샘플에서 string 타입의 Path 파라미터를 처리하기가 곤란했기 때문입니다. 가령, /payments/{paymentId}/cash-receipt 엔드포인트의 경우에는 paymentId 파라미터가 빈 문자열이면 /payments//cash-receipt 형태로 샘플 코드가 생성되기 때문에 이를 방지하기 위해 기본값을 파라미터 이름으로 설정했습니다.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
developers	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 22, 2024 7:19am

[disjukr]

멋진 기능입니다. 다만 지금 화면의 세로 공간을 충분히 활용하고있지 않은 것 같습니다.

[CirnoV]

@disjukr
기존과 동일한 공간에서 요청예제와 응답예제를 추가로 보여주기 위해 그리드를 2개에서 4개로 늘려서 각각의 컴포넌트 높이가 줄어들었습니다.

[disjukr]

request body를 입력하기 위한 공간이 많이 부족한 것 같은데요, 이 부분이 불편하지 않을까요?

[XiNiHa]

네넹 제가 보기에도 UI 컴포넌트 4개를 구겨넣기보다는 탭 형태로 TRY랑 SAMPLE을 나눠 둔다던가 하는 게 나을 것 같아요

[CirnoV]

Request 값에 따라서 Request Sample이 생성되는 방식이라 둘을 분리하기가 뭔가 애매하네요... 혹시 좋은 방법이 없을까요?

[XiNiHa]

음 아니면 Request/Response를 탭 UI로 만들어도 좋을 것 같네요 (요청 실행 시 자동으로 Response 탭으로 넘어가도록 하고)

[CirnoV]

제 생각에는 Response Sample을 한눈에 보는것도 중요할 것 같아서 Response 결과만 탭으로 넘기고, 나머지 3개의 그리드 크기를 조정해서 Request에 비중을 더 주면 괜찮을 것 같은데 어떤가요?

[XiNiHa]

음 한번 적용해보고 크기를 봐야지 감을 잡을 수 있을 것 같은데, 개인적으로 생각하기에는 높이가 너무 작아지면 여러모로 너무 불편해질 것 같아서 (특히 응답 예제는 상당히 길어질 수도 있을 것 같아가지고) 좀 꺼려지긴 하네요

[CirnoV]

네 그러면 탭을 한번 적용해보고 생각해봐야겠네요

[XiNiHa]

사실 Monaco readonly로 넣는 게 나을지 그냥 Shiki 같은 거 돌리는 게 나을지 잘 모르겠긴 하네요

[CirnoV]

일단 통일성 있게 같은 에디터로 작업했는데, 어차피 readonly면 그렇게 하고 복사 버튼 하나 넣어도 상관없겠군요

[CirnoV]

@XiNiHa 일단 Request / Response 탭을 만들어서 분리해봤어요