# 응답으로 만드는 명세 (/ko/docs/specs/specs-from-traffic)

명세보다 요청이 먼저 있을 때가 많습니다. 누군가 가져온 컬렉션이나, API를 살펴보면서 시험해 본 호출입니다. **응답으로 새로운 명세 만들기**는
이것을 OpenAPI 문서로 바꿉니다. 각 요청은 마지막으로 받은 응답을 바탕으로 문서화된 작업이 됩니다. 경로와 매개변수, 보낸 본문, 그리고
본문의 JSON 스키마와 예제가 있는 응답이 들어갑니다. 이미 가지고 있는 명세에 추가하면 부족한 부분만 채워집니다.

## 폴더 문서화 [#documenting-a-folder]

<Steps>
<Step>

문서화할 요청을 보내서 각각 응답이 있게 합니다. 예를 들어 Alpenglow에서는 **Catalog** 폴더의 요청을 보냅니다.

</Step>
<Step>

요청 사이드바에서 폴더를 오른쪽 클릭하고 <strong>OpenAPI 명세에 문서화…</strong>를 선택합니다. 작업 공간 전체를 문서화하려면 명세 사이드바에서 <strong>+</strong> ›
<strong>응답으로 새로운 명세 만들기…</strong>, 비어 있는 명세 페이지에서 <strong>응답에서…</strong>, 또는 명령 팔레트에서 <strong>응답으로 새로운 명세 만들기…</strong>를
선택합니다.

</Step>
<Step>

**OpenAPI 명세에 문서화** 시트에서 선택 사항을 확인합니다.

| 선택 사항 | 의미 |
| --- | --- |
| **요청** | **작업 공간 전체**, 또는 폴더 하나. 하위 폴더의 요청도 포함됩니다. |
| **명세** | **새로운 명세**, 또는 추가할 작업 공간의 명세. 이미 명세를 따르는 폴더는 그 명세에 추가됩니다. |
| **제목** | 새 명세의 제목. 처음에는 폴더 이름, 또는 작업 공간 이름입니다. |
| **“폴더 이름” 폴더를 명세에 연결** | 기본으로 켜져 있습니다. 그러면 폴더의 요청이 자신이 된 작업을 따르므로, 이후 명세의 변경 사항을 요청에 적용할 수 있습니다. |

</Step>
<Step>

**문서화**를 클릭합니다. 시트에 결과가 표시되며, **명세 열기**를 누르면 결과가 열립니다.

</Step>
</Steps>

<Shot id="specs-from-responses" alt="Catalog 폴더를 문서화한 뒤의 OpenAPI 명세에 문서화 시트: 새로운 작업, 이유와 함께 제외된 요청, 명세 열기 버튼이 보입니다" />

## 만들어지는 것 [#what-you-get]

결과에는 다음이 나열됩니다.

| 제목 | 의미 |
| --- | --- |
| **새로운 작업** | `GET /products/{sku}`처럼 명세에 없던 작업. |
| **응답 추가됨** | 이미 있던 작업 중 `404`처럼 다른 응답이 새로 문서화된 것. |
| **이미 문서화됨** | 응답된 그대로 명세에 이미 문서화되어 있던 작업. 바뀐 것이 없습니다. |
| **제외됨** | 문서화되지 않은 요청과 각각의 이유. |

또한 작업을 따르게 된 요청의 수와, 결과에서 린트가 찾은 오류의 수(있다면)도 알려 줍니다.

각 작업에 들어가는 내용은 다음과 같습니다.

- **경로**: OpenAPI 형식으로. 변수에서 온 경로 구간은 경로 매개변수가 되며, 보낸 값과 함께 문서화됩니다. URL의 서버 부분은 경로에서
  제외됩니다.
- 요청이 설정한 **쿼리 매개변수와 헤더**.
- **요청 본문**과 **응답**: 본문으로 만든 JSON 스키마와 예제가 함께 들어갑니다. 큰 예제는 제외되고 스키마는 남으며, 긴 배열은 예제에 몇 개
  항목만 남깁니다.
- 작업의 요약으로 **요청 이름**, 작업의 태그로 **요청의 하위 폴더**.
- 보안 스킴으로 **요청의 인증**. OpenAPI에 해당 스킴이 없는 경우(디바이스 코드 방식의 OAuth 2) 그렇다는 메모가 남습니다.

비밀 값은 가려집니다. 비밀 변수와, 비밀처럼 보이는 키(토큰, 암호, 키) 아래의 값은 예제에서 `••••••`로 표시됩니다.

## 가지고 있는 명세에 추가 [#adding-to-a-spec-you-have]

**명세**에서 명세를 선택하세요. Echolot은 부족한 것만 추가합니다. 아직 이름이 없는 작업, 응답, 스키마, 보안 스킴입니다. 명세에 이미 있는
내용은 작성된 그대로 유지됩니다. Swagger 2.0 명세에는 추가할 수 없으며 OpenAPI 3 문서만 가능합니다.

## 기록에서 응답 하나씩 문서화 [#documenting-single-responses-from-history]

[기록](/docs/workspaces/history)에서 응답을 받은 HTTP 교환을 오른쪽 클릭하고 <strong>OpenAPI 명세에 추가…</strong>를 선택하세요. 그 응답 하나에 대해
같은 시트가 열립니다. 오류처럼 한 번 본 응답에 편리합니다.

## 제외되는 것 [#what-is-left-out]

- HTTP가 아닌 요청(GraphQL, gRPC, WebSocket 등): OpenAPI에는 HTTP 요청만 문서화됩니다.
- 아직 응답이 없는 요청: 먼저 보내세요.
- 응답을 받기 전에 보내기에 실패한 요청.
- 자체 명세를 따르는 하위 폴더에 있는 요청.

## 최신 상태 유지 [#keep-it-current]

폴더가 명세를 따르게 되면 명세가 계약입니다. 명세 페이지에서 편집하고, <strong>“폴더 이름” 폴더의 변경 사항 확인…</strong>으로 변경 사항을 요청에
적용하세요. [명세를 따르는 요청](/docs/specs#requests-that-follow-the-spec)을 참고하세요. 명세의 응답을 [모의 서버](/docs/mocks)에
제공해서 프런트엔드가 그것으로 작업하게 할 수도 있습니다.

**명세** 도구 모음이 켜져 있으면 에이전트도 `add_to_spec` 도구로 같은 일을 할 수 있습니다. [에이전트](/docs/ai/agents)를 참고하세요.