Echolot응답으로 만드는 명세
보낸 요청과 받은 응답으로 OpenAPI 명세를 작성합니다.
명세보다 요청이 먼저 있을 때가 많습니다. 누군가 가져온 컬렉션이나, API를 살펴보면서 시험해 본 호출입니다. 응답으로 새로운 명세 만들기는 이것을 OpenAPI 문서로 바꿉니다. 각 요청은 마지막으로 받은 응답을 바탕으로 문서화된 작업이 됩니다. 경로와 매개변수, 보낸 본문, 그리고 본문의 JSON 스키마와 예제가 있는 응답이 들어갑니다. 이미 가지고 있는 명세에 추가하면 부족한 부분만 채워집니다.
폴더 문서화
문서화할 요청을 보내서 각각 응답이 있게 합니다. 예를 들어 Alpenglow에서는 Catalog 폴더의 요청을 보냅니다.
요청 사이드바에서 폴더를 오른쪽 클릭하고 OpenAPI 명세에 문서화…를 선택합니다. 작업 공간 전체를 문서화하려면 명세 사이드바에서 + › 응답으로 새로운 명세 만들기…, 비어 있는 명세 페이지에서 응답에서…, 또는 명령 팔레트에서 응답으로 새로운 명세 만들기…를 선택합니다.
OpenAPI 명세에 문서화 시트에서 선택 사항을 확인합니다.
| 선택 사항 | 의미 |
|---|---|
| 요청 | 작업 공간 전체, 또는 폴더 하나. 하위 폴더의 요청도 포함됩니다. |
| 명세 | 새로운 명세, 또는 추가할 작업 공간의 명세. 이미 명세를 따르는 폴더는 그 명세에 추가됩니다. |
| 제목 | 새 명세의 제목. 처음에는 폴더 이름, 또는 작업 공간 이름입니다. |
| “폴더 이름” 폴더를 명세에 연결 | 기본으로 켜져 있습니다. 그러면 폴더의 요청이 자신이 된 작업을 따르므로, 이후 명세의 변경 사항을 요청에 적용할 수 있습니다. |
문서화를 클릭합니다. 시트에 결과가 표시되며, 명세 열기를 누르면 결과가 열립니다.
만들어지는 것
결과에는 다음이 나열됩니다.
| 제목 | 의미 |
|---|---|
| 새로운 작업 | GET /products/{sku}처럼 명세에 없던 작업. |
| 응답 추가됨 | 이미 있던 작업 중 404처럼 다른 응답이 새로 문서화된 것. |
| 이미 문서화됨 | 응답된 그대로 명세에 이미 문서화되어 있던 작업. 바뀐 것이 없습니다. |
| 제외됨 | 문서화되지 않은 요청과 각각의 이유. |
또한 작업을 따르게 된 요청의 수와, 결과에서 린트가 찾은 오류의 수(있다면)도 알려 줍니다.
각 작업에 들어가는 내용은 다음과 같습니다.
- 경로: OpenAPI 형식으로. 변수에서 온 경로 구간은 경로 매개변수가 되며, 보낸 값과 함께 문서화됩니다. URL의 서버 부분은 경로에서 제외됩니다.
- 요청이 설정한 쿼리 매개변수와 헤더.
- 요청 본문과 응답: 본문으로 만든 JSON 스키마와 예제가 함께 들어갑니다. 큰 예제는 제외되고 스키마는 남으며, 긴 배열은 예제에 몇 개 항목만 남깁니다.
- 작업의 요약으로 요청 이름, 작업의 태그로 요청의 하위 폴더.
- 보안 스킴으로 요청의 인증. OpenAPI에 해당 스킴이 없는 경우(디바이스 코드 방식의 OAuth 2) 그렇다는 메모가 남습니다.
비밀 값은 가려집니다. 비밀 변수와, 비밀처럼 보이는 키(토큰, 암호, 키) 아래의 값은 예제에서 ••••••로 표시됩니다.
가지고 있는 명세에 추가
명세에서 명세를 선택하세요. Echolot은 부족한 것만 추가합니다. 아직 이름이 없는 작업, 응답, 스키마, 보안 스킴입니다. 명세에 이미 있는 내용은 작성된 그대로 유지됩니다. Swagger 2.0 명세에는 추가할 수 없으며 OpenAPI 3 문서만 가능합니다.
기록에서 응답 하나씩 문서화
기록에서 응답을 받은 HTTP 교환을 오른쪽 클릭하고 OpenAPI 명세에 추가…를 선택하세요. 그 응답 하나에 대해 같은 시트가 열립니다. 오류처럼 한 번 본 응답에 편리합니다.
제외되는 것
- HTTP가 아닌 요청(GraphQL, gRPC, WebSocket 등): OpenAPI에는 HTTP 요청만 문서화됩니다.
- 아직 응답이 없는 요청: 먼저 보내세요.
- 응답을 받기 전에 보내기에 실패한 요청.
- 자체 명세를 따르는 하위 폴더에 있는 요청.
최신 상태 유지
폴더가 명세를 따르게 되면 명세가 계약입니다. 명세 페이지에서 편집하고, “폴더 이름” 폴더의 변경 사항 확인…으로 변경 사항을 요청에 적용하세요. 명세를 따르는 요청을 참고하세요. 명세의 응답을 모의 서버에 제공해서 프런트엔드가 그것으로 작업하게 할 수도 있습니다.
명세 도구 모음이 켜져 있으면 에이전트도 add_to_spec 도구로 같은 일을 할 수 있습니다. 에이전트를 참고하세요.