# 명세 편집 (/ko/docs/specs/editing)
명세는 두 가지 방식으로 편집하며, 페이지 헤더의 **편집기**로 언제든 전환할 수 있습니다. 카드와 필드로 편집하는 **시각적**, YAML 또는 JSON
자체를 편집하는 **코드**입니다. 두 방식 모두 같은 텍스트를 바꿉니다. Echolot이 보관하는 것은 텍스트이므로, 시각적 편집은 편집한 부분의
줄만 바꿉니다. 그래서 주석, 순서, 서식이 그대로 유지되고 Git diff에서 무엇이 바뀌었는지 정확히 볼 수 있습니다.
명세를 시작하려면 사이드바의 **명세** 헤더에서 **+** › **새로운 명세**를 선택하세요. Echolot이 제목이 `New API`인 OpenAPI 3.1 문서를
`specs` 폴더에 만들고 시각적 편집기에서 엽니다.
## 시각적 편집기 [#the-visual-editor]
시각적 편집기의 필드는 편집을 마치면 문서를 바꿉니다. ↩를 누르거나 다른 필드로 이동하세요. 설명 필드는 Markdown을 받으며
↩로 줄을 바꿉니다. 필드 옆의 버튼은 설명이 어떻게 읽힐지 보여 줍니다.
페이지에는 다음 카드가 있습니다.
| 카드 | 편집하는 내용 |
| --- | --- |
| **개요** | API의 **제목**, **버전**, **설명**. |
| 서버 | 서버의 URL과 설명. 서버 추가로 추가하고 −로 제거합니다. 서버가 없으면 명세에서 만든 요청은 직접 설정하는 `{{baseUrl}}`로 시작합니다. |
| **연락처 및 라이선스** | **보기**를 누르면 연락처 이름, 이메일, URL, 라이선스와 그 URL, 서비스 약관이 열립니다. |
| **엔드포인트** | 모든 작업. **그룹화 기준**은 **경로** 또는 **태그**로 나열합니다(태그가 없는 것은 **태그 없음** 아래). 클릭하면 열립니다. |
| **스키마** | 본문과 응답이 이름으로 참조할 수 있는 재사용 가능한 스키마. 클릭하면 열립니다. |
### 엔드포인트 추가 [#adding-an-endpoint]
**엔드포인트** 카드에서 **엔드포인트 추가**를 클릭합니다. **새로운 엔드포인트** 시트에서 메서드를 고르고 경로(예: `/products/{sku}`)를
입력합니다. 요약과 태그는 선택 사항입니다. 그런 다음 **엔드포인트 추가**를 클릭하세요. Echolot이 경로의 매개변수를 정의하고, 시작점이 되는
본문과 성공 응답을 추가합니다. 이미 있는 메서드와 경로는 거부됩니다.
열려 있는 엔드포인트에는 다음이 있습니다.
| 부분 | 편집하는 내용 |
| --- | --- |
| **엔드포인트** | 메서드와 경로. 바꾸면 작업이 이동합니다. |
| **요약**, **설명** | `List products` 같은 짧은 이름, 그리고 작업이 하는 일, 필요한 것, 반환하는 것. |
| **작업 ID**, **태그** | 코드 생성기가 사용하는 ID, 그리고 쉼표로 구분한 태그. |
| **더 이상 사용되지 않음** | 작업을 더 이상 사용되지 않는 것으로 표시합니다. |
| **매개변수** | 각 매개변수의 이름, 위치(**위치**: `path`, `query`, `header`, `cookie`), 타입, **필수** 여부, 설명. **매개변수 추가**로 추가합니다. 경로에 정의되지 않은 매개변수가 있으면 **\{sku\} 추가** 같은 버튼으로 정의합니다. **경로 공통**으로 표시된 매개변수는 경로의 모든 메서드에 대해 정의된 것입니다. |
| **요청 본문** | **본문 추가**는 JSON 본문을 추가합니다. 각 미디어 타입에 스키마가 있고 본문을 **필수**로 지정할 수 있습니다. **본문 제거**로 뺍니다. |
| **응답** | 상태 코드마다 한 행이 있으며 설명이 있고, **본문 추가** 후에는 미디어 타입과 스키마도 있습니다. **응답 추가**는 아직 사용하지 않은 다음 일반 코드(200, 201, 204, 400, 401, 403, 404, 409, 422, 500, 그다음 `default`)를 추가합니다. 코드를 편집해 바꿉니다. 작업에는 응답이 하나 이상 있어야 합니다. |
매개변수, 본문, 속성의 타입은 메뉴로 고릅니다. 재사용 가능한 스키마, `string`, `integer`, `number`, `boolean`, `object`, 이 중 어느 것의
**배열**, 또는 **없음**입니다. 메뉴로 표현할 수 없는 스키마는 작성된 그대로 표시되며, 다른 것을 고를 때까지 유지됩니다.
열려 있는 엔드포인트의 맨 아래에는 린트가 찾은 첫 번째 문제(포인터를 올리면 모든 문제가 보입니다)와 세 개의 버튼이 있습니다.
**요청 열기**(이 작업을 따르는 요청이 있을 때), **코드에서 보기**, **엔드포인트 삭제**입니다.
### 스키마 추가 [#adding-a-schema]
**스키마** 카드에서 **스키마 추가**를 클릭하고 `Product` 같은 이름을 붙인 다음 **추가**를 클릭합니다. 열려 있는 스키마에는 **이름**,
**설명**, **속성**이 있습니다. 속성은 각각 이름, 타입, **필수** 여부, 설명이 있습니다. **속성 추가**로 추가합니다.
스키마는 어디에서 사용되는지 알려 줍니다(**3곳에서 사용됨** 또는 **아직 사용되지 않음**). 이름을 바꾸면 모든 참조가 바뀝니다. 스키마가
사용 중일 때 **스키마 삭제**는 먼저 확인을 요청합니다. 그 참조가 아무것도 가리키지 않게 되기 때문입니다. 일반 객체가 아닌 스키마는 코드에서
설명하고 편집합니다. **코드에서 보기**로 이동하세요.
### Swagger 2.0 [#swagger-20]
Swagger 2.0 문서는 시각적 편집기에서 읽기 전용으로 열리며, 편집은 **코드**에서 합니다. Echolot이 설계하는 것은 OpenAPI 3입니다.
## 코드 편집기 [#the-code-editor]
YAML 또는 JSON을 직접 편집하려면 **편집기**를 **코드**로 전환하세요. 린트는 입력하는 동안 잠시 멈추면 실행됩니다. 오류와 경고는 해당 줄에
밑줄로 표시되고, 포인터를 올리면 메시지가 나타납니다.
`$ref` 위에 포인터를 올리면 가리키는 대상이 보이고, ⌘-클릭하면 그곳으로 이동합니다. 다른 파일에 대한 참조는 그 파일을 엽니다.
명세가 참조하는 파일은 항상 코드로 열립니다.
텍스트를 구문 분석할 수 없으면 시각적 편집기에 시각적 편집기를 사용하려면 구문 분석할 수 있는 문서가 필요합니다.와 함께 줄과 오류가
표시됩니다. **코드에서 수정**을 누르면 그 줄로 이동합니다.
## 저장 [#saving]
직접 저장할 필요는 없습니다. Echolot은 변경할 때마다 잠시 후, 그리고 다른 명세로 전환하거나 페이지를 떠나거나 윈도우를 닫을 때 명세를
기록합니다. 해당 명세의 실행 중인 모의 서버는 변경 사항을 반영합니다.
파일을 쓸 수 없으면(예: 읽기 전용이 된 경우) Echolot이 **명세를 저장할 수 없음**이라고 알리고 편집한 내용을 편집기에 그대로 둡니다.
| 버튼 | 하는 일 |
| --- | --- |
| **재시도** | 파일 쓰기를 다시 시도합니다. |
| **사본 저장…** | 선택한 파일에 편집한 내용을 씁니다. |
| **변경 사항 폐기** | 디스크에 있는 파일 상태로 되돌립니다. |
| **계속 편집** | 메시지를 닫습니다. 편집한 내용은 유지되며, 저장될 때까지 페이지는 이 명세에 머뭅니다. |
## 실행 취소 [#undo]
**편집 › 실행 취소**(⌘Z)는 두 편집기 모두에서 편집을 취소하고, **편집 › 실행 복귀**
(⇧⌘Z)는 되돌립니다. 시각적 편집은 하나가 한 단계이며, 입력은 잠시 멈출 때까지가 한 단계입니다. 실행 취소는
바꾼 명세에 속합니다. 다른 파일을 열고 나면 그 이전 파일에는 적용되지 않습니다.
## 에이전트와 함께 [#with-an-agent]
외부 [에이전트](/docs/ai/agents)에 대해 **설정 › 에이전트**에서 **명세** 도구 모음을 켜면 작업 공간의 명세를 읽고, 쓰고, 린트할 수 있습니다.