stly

stly spec-documents

이 페이지의 내용

이 페이지는 공개 계약에서 생성하며 설명은 원문(한국어) 그대로 표시합니다.

stly spec-documents create#

스펙 문서 생성

HTTP 요청: POST /api/spec-documents
인증 모드: Agent 토큰, User 세션
기록 변경: 예
입력 JSON(--input) 필수

입력 JSON 구조는 stly schema spec-documents create로 확인합니다.

옵션

이름	타입	필수	설명
`--input`	`string`	예	JSON 원문 파일 또는 stdin(-)
`--fields`	`string`	아니요	응답 최상위 필드, 쉼표로 구분 값: `id`, `repository_id`, `api_id`, `kind`, `name`, `path`, `summary`, `description`, `spec_version`, `content_format`, `created_at`, `updated_at`, `content`
`--repository`	`string`	아니요	부모 Repository ID(스펙 문서 생성·목록에서는 선택)

공통 옵션: --server, --env-file, --timeout, --auth-mode, --dry-run

예시

stly spec-documents create --repository 00000000-0000-0000-0000-000000000001 --input input.json

stly spec-documents delete#

스펙 문서 삭제

HTTP 요청: DELETE /api/spec-documents/{id}
인증 모드: Agent 토큰, User 세션
기록 변경: 예
--if-match 필수

인수

id: ID

옵션

이름	타입	필수	설명
`--if-match`	`string`	예	상세 GET에서 얻은 단일 strong ETag
`--fields`	`string`	아니요	응답 최상위 필드, 쉼표로 구분

공통 옵션: --server, --env-file, --timeout, --auth-mode, --dry-run

예시

stly spec-documents delete 00000000-0000-0000-0000-000000000001 --if-match '"상세 GET의 ETag"'

stly spec-documents export#

승인한 Catalog 값을 OpenAPI 원문·manifest에 반영(서버 저장 없음)

HTTP 요청: POST /api/spec-documents/{id}/export
인증 모드: Agent 토큰, User 세션
기록 변경: 예
입력 JSON(--input) 필수
--if-match 필수

입력 JSON 구조는 stly schema spec-documents export로 확인합니다.

인수

file: OpenAPI 원문 (ID 인자는 --file·--input 방식에서 사용)

옵션

이름	타입	필수	설명
`--if-match`	`string`	예	같은 원문·manifest·path의 export-plan 응답 plan_token
`--approve`	`string`	아니요	승인할 변경 ID의 쉼표 구분 목록
`--approve-all`	`boolean`	아니요	현재 --if-match 계획 토큰 안의 지원 변경 전체 승인
`--fields`	`string`	아니요	응답 최상위 필드, 쉼표로 구분 값: `applicable`, `changes`, `content`, `errors`, `manifest`, `plan_token`, `unsupported`, `warnings`
`--file`	`string`	아니요	반영할 OpenAPI 로컬 파일. --input과 함께 사용할 수 없습니다
`--input`	`string`	아니요	HTTP 요청 JSON. --file 사용 시 생략합니다
`--manifest`	`string`	아니요	structly.yaml 경로. 생략하면 현재 디렉터리에서 상위로 탐색합니다

공통 옵션: --server, --env-file, --timeout, --auth-mode, --dry-run

동작

현재 디렉터리부터 manifest 탐색. 읽기 전용 manifest-plan으로 연결 확인·문서 ID 복구
원문·manifest·선택 옵션으로 계획 확인. 계획 명령은 서버·파일 저장 없음
같은 토큰과 --approve 또는 --approve-all로 반영. 412·토큰 변경 시 자동 재계획·반영 없음
쓰기 직전 파일 SHA-256 확인. 충돌 시 manifest.new 또는 원문.new를 보존하고 실패

예시

stly spec-documents export openapi.yaml --manifest structly.yaml --approve api.name --if-match '"export-plan:계획 토큰"'

stly spec-documents export-plan#

Catalog 값을 OpenAPI 원문으로 되돌릴 승인 계획(저장 없음)

HTTP 요청: POST /api/spec-documents/{id}/export-plan
인증 모드: Agent 토큰, User 세션
기록 변경: 아니요
입력 JSON(--input) 필수

입력 JSON 구조는 stly schema spec-documents export-plan로 확인합니다.

인수

file: OpenAPI 원문 (ID 인자는 --file·--input 방식에서 사용)

옵션

이름	타입	필수	설명
`--fields`	`string`	아니요	응답 최상위 필드, 쉼표로 구분 값: `applicable`, `changes`, `content`, `errors`, `manifest`, `plan_token`, `unsupported`, `warnings`
`--file`	`string`	아니요	반영할 OpenAPI 로컬 파일. --input과 함께 사용할 수 없습니다
`--input`	`string`	아니요	HTTP 요청 JSON. --file 사용 시 생략합니다
`--manifest`	`string`	아니요	structly.yaml 경로. 생략하면 현재 디렉터리에서 상위로 탐색합니다

공통 옵션: --server, --env-file, --timeout, --auth-mode, --dry-run

동작

현재 디렉터리부터 manifest 탐색. 읽기 전용 manifest-plan으로 연결 확인·문서 ID 복구
원문·manifest·선택 옵션으로 계획 확인. 계획 명령은 서버·파일 저장 없음
같은 토큰과 --approve 또는 --approve-all로 반영. 412·토큰 변경 시 자동 재계획·반영 없음
쓰기 직전 파일 SHA-256 확인. 충돌 시 manifest.new 또는 원문.new를 보존하고 실패

예시

stly spec-documents export-plan openapi.yaml --manifest structly.yaml

stly spec-documents get#

스펙 문서 상세 조회

HTTP 요청: GET /api/spec-documents/{id}
인증 모드: Agent 토큰, User 세션
기록 변경: 아니요

인수

id: ID

옵션

이름	타입	필수	설명
`--fields`	`string`	아니요	응답 최상위 필드, 쉼표로 구분 값: `id`, `repository_id`, `api_id`, `kind`, `name`, `path`, `summary`, `description`, `spec_version`, `content_format`, `created_at`, `updated_at`, `content`

공통 옵션: --server, --env-file, --timeout, --auth-mode, --dry-run

예시

stly spec-documents get 00000000-0000-0000-0000-000000000001

stly spec-documents import#

승인한 OpenAPI import 변경과 원문 반영

HTTP 요청: POST /api/spec-documents/{id}/import
인증 모드: Agent 토큰, User 세션
기록 변경: 예
입력 JSON(--input) 필수
--if-match 필수

입력 JSON 구조는 stly schema spec-documents import로 확인합니다.

인수

file: OpenAPI 원문 (ID 인자는 --file·--input 방식에서 사용)

옵션

이름	타입	필수	설명
`--if-match`	`string`	예	같은 본문(approved 제외)으로 실행한 import-plan 응답의 plan_token
`--api`	`string`	아니요	소속 API ID(선택, 지정 시 해당 API 소속 Endpoint만 조회)
`--approve`	`string`	아니요	승인할 변경 ID의 쉼표 구분 목록
`--approve-all`	`boolean`	아니요	현재 --if-match 계획 토큰 안의 지원 변경 전체 승인
`--create-api`	`string`	아니요	생성할 API의 name·handle JSON 객체
`--create-service`	`string`	아니요	생성할 Service의 name·handle JSON 객체
`--fields`	`string`	아니요	응답 최상위 필드, 쉼표로 구분 값: `api_id`, `applicable`, `changes`, `deletion_candidates`, `errors`, `items`, `manifest`, `plan_token`, `security_impacts`, `warnings`
`--file`	`string`	아니요	반영할 OpenAPI 로컬 파일. --input과 함께 사용할 수 없습니다
`--input`	`string`	아니요	HTTP 요청 JSON. --file 사용 시 생략합니다
`--link`	`string`	아니요	operationId → Endpoint ID JSON 객체
`--manifest`	`string`	아니요	structly.yaml 경로. 생략하면 현재 디렉터리에서 상위로 탐색합니다
`--none`	`boolean`	아니요	제공 Service를 명시적으로 미연결
`--recreate`	`string`	아니요	재생성할 operationId의 쉼표 구분 목록
`--rename`	`string`	아니요	이전 operationId → 새 operationId JSON 객체
`--service`	`string`	아니요	제공 Service ID

공통 옵션: --server, --env-file, --timeout, --auth-mode, --dry-run

동작

현재 디렉터리부터 manifest 탐색. 읽기 전용 manifest-plan으로 연결 확인·문서 ID 복구
원문·manifest·선택 옵션으로 계획 확인. 계획 명령은 서버·파일 저장 없음
같은 토큰과 --approve 또는 --approve-all로 반영. 412·토큰 변경 시 자동 재계획·반영 없음
쓰기 직전 파일 SHA-256 확인. 충돌 시 manifest.new 또는 원문.new를 보존하고 실패

예시

stly spec-documents import openapi.yaml --manifest structly.yaml --approve api.name --if-match '"import-plan:계획 토큰"'

stly spec-documents import-plan#

OpenAPI 원문의 변경 ID별 import 계획(저장 없음)

HTTP 요청: POST /api/spec-documents/{id}/import-plan
인증 모드: Agent 토큰, User 세션
기록 변경: 아니요
입력 JSON(--input) 필수

입력 JSON 구조는 stly schema spec-documents import-plan로 확인합니다.

인수

file: OpenAPI 원문 (ID 인자는 --file·--input 방식에서 사용)

옵션

이름	타입	필수	설명
`--api`	`string`	아니요	소속 API ID(선택, 지정 시 해당 API 소속 Endpoint만 조회)
`--create-api`	`string`	아니요	생성할 API의 name·handle JSON 객체
`--create-service`	`string`	아니요	생성할 Service의 name·handle JSON 객체
`--fields`	`string`	아니요	응답 최상위 필드, 쉼표로 구분 값: `api_id`, `applicable`, `changes`, `deletion_candidates`, `errors`, `items`, `manifest`, `plan_token`, `security_impacts`, `warnings`
`--file`	`string`	아니요	반영할 OpenAPI 로컬 파일. --input과 함께 사용할 수 없습니다
`--input`	`string`	아니요	HTTP 요청 JSON. --file 사용 시 생략합니다
`--link`	`string`	아니요	operationId → Endpoint ID JSON 객체
`--manifest`	`string`	아니요	structly.yaml 경로. 생략하면 현재 디렉터리에서 상위로 탐색합니다
`--none`	`boolean`	아니요	제공 Service를 명시적으로 미연결
`--recreate`	`string`	아니요	재생성할 operationId의 쉼표 구분 목록
`--rename`	`string`	아니요	이전 operationId → 새 operationId JSON 객체
`--service`	`string`	아니요	제공 Service ID

공통 옵션: --server, --env-file, --timeout, --auth-mode, --dry-run

동작

현재 디렉터리부터 manifest 탐색. 읽기 전용 manifest-plan으로 연결 확인·문서 ID 복구
원문·manifest·선택 옵션으로 계획 확인. 계획 명령은 서버·파일 저장 없음
같은 토큰과 --approve 또는 --approve-all로 반영. 412·토큰 변경 시 자동 재계획·반영 없음
쓰기 직전 파일 SHA-256 확인. 충돌 시 manifest.new 또는 원문.new를 보존하고 실패

예시

stly spec-documents import-plan openapi.yaml --manifest structly.yaml

stly spec-documents list#

스펙 문서 목록 조회

HTTP 요청: GET /api/spec-documents
인증 모드: Agent 토큰, User 세션
기록 변경: 아니요

옵션

이름	타입	필수	설명
`--fields`	`string`	아니요	응답 최상위 필드, 쉼표로 구분 값: `id`, `repository_id`, `api_id`, `kind`, `name`, `path`, `summary`, `description`, `spec_version`, `content_format`, `created_at`, `updated_at`
`--repository`	`string`	아니요	부모 Repository ID(스펙 문서 생성·목록에서는 선택)
`--standalone`	`string`	아니요	Repository 없는 OpenAPI 목록 조회에 true 지정

공통 옵션: --server, --env-file, --timeout, --auth-mode, --dry-run

예시

stly spec-documents list --repository 00000000-0000-0000-0000-000000000001

stly spec-documents manifest#

서버 기준 단일 문서 structly.yaml 조회

HTTP 요청: GET /api/spec-documents/{id}/manifest
인증 모드: Agent 토큰, User 세션
기록 변경: 아니요

인수

id: ID

옵션

이름	타입	필수	설명
`--fields`	`string`	아니요	응답 최상위 필드, 쉼표로 구분 값: `manifest`

공통 옵션: --server, --env-file, --timeout, --auth-mode, --dry-run

예시

stly spec-documents manifest 00000000-0000-0000-0000-000000000001

stly spec-documents manifest-plan#

manifest 연결 확인·문서 식별·등록 키 준비(서버 저장 없음)

HTTP 요청: POST /api/spec-documents/manifest-plan
인증 모드: Agent 토큰, User 세션
기록 변경: 아니요
입력 JSON(--input) 필수

입력 JSON 구조는 stly schema spec-documents manifest-plan로 확인합니다.

옵션

이름	타입	필수	설명
`--input`	`string`	예	JSON 원문 파일 또는 stdin(-)
`--fields`	`string`	아니요	응답 최상위 필드, 쉼표로 구분 값: `document_id`, `manifest`, `organization_id`, `registration_key`, `repository_id`, `server`

공통 옵션: --server, --env-file, --timeout, --auth-mode, --dry-run

예시

stly spec-documents manifest-plan --input input.json

stly spec-documents register#

OpenAPI 파일 등록과 manifest ID 기록

HTTP 요청: POST /api/spec-documents
인증 모드: Agent 토큰, User 세션
기록 변경: 예
입력 JSON(--input) 필수

입력 JSON 구조는 stly schema spec-documents register로 확인합니다.

인수

file: OpenAPI 원문 (ID 인자는 --file·--input 방식에서 사용)

옵션

이름	타입	필수	설명
`--name`	`string`	예	등록할 스펙 문서 이름
`--description`	`string`	아니요	스펙 문서 설명
`--fields`	`string`	아니요	응답 최상위 필드, 쉼표로 구분 값: `id`, `repository_id`, `api_id`, `kind`, `name`, `path`, `summary`, `description`, `spec_version`, `content_format`, `created_at`, `updated_at`, `content`
`--file`	`string`	아니요	반영할 OpenAPI 로컬 파일. --input과 함께 사용할 수 없습니다
`--manifest`	`string`	아니요	structly.yaml 경로. 생략하면 현재 디렉터리에서 상위로 탐색합니다
`--repository`	`string`	아니요	부모 Repository ID(스펙 문서 생성·목록에서는 선택)
`--summary`	`string`	아니요	스펙 문서 요약

공통 옵션: --server, --env-file, --timeout, --auth-mode, --dry-run

동작

읽기 전용 manifest-plan으로 서버·Organization·Repository 확인 및 등록 키 준비
manifest에 등록 키를 해시 확인·임시 파일 교체로 먼저 저장
같은 키로 원문 등록. 성공 후 서버가 병합한 document_id를 manifest에 기록. 실패·중단은 키로 재시도

예시

stly spec-documents register openapi.yaml --manifest structly.yaml --name Orders

stly spec-documents update#

스펙 문서 수정

HTTP 요청: PUT /api/spec-documents/{id}
인증 모드: Agent 토큰, User 세션
기록 변경: 예
입력 JSON(--input) 필수
--if-match 필수

입력 JSON 구조는 stly schema spec-documents update로 확인합니다.

인수

id: ID

옵션

이름	타입	필수	설명
`--if-match`	`string`	예	상세 GET에서 얻은 단일 strong ETag
`--input`	`string`	예	JSON 원문 파일 또는 stdin(-)
`--fields`	`string`	아니요	응답 최상위 필드, 쉼표로 구분 값: `id`, `repository_id`, `api_id`, `kind`, `name`, `path`, `summary`, `description`, `spec_version`, `content_format`, `created_at`, `updated_at`, `content`

공통 옵션: --server, --env-file, --timeout, --auth-mode, --dry-run

예시

stly spec-documents update 00000000-0000-0000-0000-000000000001 --input input.json --if-match '"상세 GET의 ETag"'

stly spec-documents view#

스펙 문서 구조 조회

HTTP 요청: GET /api/spec-documents/{id}/view
인증 모드: Agent 토큰, User 세션
기록 변경: 아니요

인수

id: ID

옵션

이름	타입	필수	설명
`--fields`	`string`	아니요	응답 최상위 필드, 쉼표로 구분 값: `value`, `source_etag`, `message`

공통 옵션: --server, --env-file, --timeout, --auth-mode, --dry-run

예시

stly spec-documents view 00000000-0000-0000-0000-000000000001