코드에만 존재하던 REST API 계약(약 663 엔드포인트)을 코어/확장 책임별로
분리된 마크다운 레퍼런스로 전면 문서화한다. 674개 규모에서 수기 문서는
반드시 drift 하므로 "코드 추출 → 스캐폴딩 → 사람이 서술 채움 → 하네스가
커버리지 강제" 하이브리드로 구성했다.
추출 파이프라인 (app/Support/ApiDoc):
- ApiRouteInventory / FormRequestIntrospector / ApiEndpointProbe(실측 HTTP) /
ResponseSchemaInferrer / ApiDocScaffolder / ColumnCommentResolver /
ResourceFieldDescriber / ParameterDescriber
- api:docgen 커맨드(--scope/--seed/--check/--dry-run/--base-url/--user) +
응답/파라미터 in-place 백필 커맨드 2종(재생성 없이 TODO 셀만 치환, 멱등)
- ApiDocSampleSeeder 계약 + 코어/확장 시더로 실측용 완전 샘플 멱등 생성
문서화 (실측 기반, GET read-only 실호출):
- 코어 291엔드포인트 35파일(docs/backend/api) + 규정 docs/backend/api-documentation.md
- 확장: ecommerce(231)·board(80)·page(17)·hello_module(2)·pay_kginicis(22)·
gdpr(15)·ckeditor5(2)·marketing(2)·verification_kginicis(1)
- 표준 4구성(헤더·요청 파라미터·응답 필드·에러 표) + 엔드포인트 용도 서술
- 파라미터 용도·응답 필드 설명 셀 전수 채움(도메인 지식 수기)
하네스:
- audit 룰 api-doc-coverage — API 표면(라우트/컨트롤러/FormRequest/Resource)
변경 시 대응 문서 미동반이면 차단. 전 대상 문서 완비로 error 승격
- file-rules 리마인더(컨트롤러/라우트 편집 시), coverage.json, dev-dashboard 카드
- docs/backend/routing.md 확장 공개 API URL 스킴 정정(/api/modules|plugins/{id})
- /AGENTS.md/docs-index 동기
8.1 KiB
Settings API 레퍼런스
소유: plugin
sirsoft-gdpr· 생성:php artisan api:docgen(실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.
TL;DR (5초 요약)
1. 이 문서는 실제 API 호출로 실측한 Settings 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 실측 응답 필드 표
3. 응답 필드의 예시값은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다
GET /api/plugins/sirsoft-gdpr/admin/settings
- 라우트명:
api.plugins.sirsoft-gdpr.admin.settings.show - 컨트롤러:
Plugins\Sirsoft\Gdpr\Http\Controllers\Admin\GdprAdminSettingsController@show - 인증/권한:
auth:sanctum+permission:sirsoft-gdpr.privacy.view
요청 파라미터
요청 파라미터 없음.
응답 필드 (data 내부)
단건 응답: data 객체의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| settings | object | {"privacy_policy_slug":"privacy","legal_entity_name":"","… |
GDPR 플러그인의 관리자 설정 전체 객체. 정책 메타데이터(slug/법인명/저장 위치), 배너 설정, 쿠키 카테고리 카탈로그, 차단 도메인을 담으며 cookie_categories 등 JSON 필드는 디코드되어 객체/배열로 노출됩니다 |
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-gdpr.privacy.view)이 없는 경우 |
설명 GDPR 플러그인의 관리자 설정 전체를 반환해 관리자 설정 화면 폼에 바인딩합니다. auth:sanctum과 sirsoft-gdpr.privacy.view 권한이 필요합니다. cookie_categories 같은 JSON 필드는 디코드하여 객체/배열로 노출합니다. 조회 전용이며 정책 버전 발행 등 부수 효과는 없습니다.
PUT /api/plugins/sirsoft-gdpr/admin/settings
- 라우트명:
api.plugins.sirsoft-gdpr.admin.settings.update - 컨트롤러:
Plugins\Sirsoft\Gdpr\Http\Controllers\Admin\GdprAdminSettingsController@update - 인증/권한:
auth:sanctum+permission:sirsoft-gdpr.privacy.update
요청 파라미터
| 이름 | 위치 | 타입 | 필수 | 허용값 | 용도 |
|---|---|---|---|---|---|
| privacy_policy_slug | body | string | 아니오 | max 100 | 개인정보 처리방침 페이지 slug(소문자·숫자·하이픈만). 비면 처리방침 링크가 비활성화되며 배너/마이페이지의 방침 링크 대상이 됩니다 |
| legal_entity_name | body | string | 아니오 | max 200 | legal entity 이름 (식별자) |
| data_storage_location | body | string | 아니오 | max 200 | 데이터 저장 위치 표기(GDPR Art.13(1)(f)/PIPA 국가 단위 안내용). IP/CIDR·클라우드 리전 코드 등 보안 민감 식별자는 검증에서 차단됩니다 |
| banner_enabled | body | boolean | 아니오 | — | 쿠키 배너와 자동 차단 엔진의 통합 활성 토글. true일 때만 배너 노출과 도메인 기반 차단이 동작합니다 |
| banner_position | body | string | 아니오 | bottom_bar, bottom_left_popup, bottom_right_popup, centered_modal |
쿠키 배너 노출 위치(하단 바/좌하단 팝업/우하단 팝업/중앙 모달) |
| cookie_categories | body | string | 아니오 | — | 쿠키 카테고리 카탈로그(JSON 문자열 또는 배열). 각 항목의 key는 necessary/functional/analytics/marketing 중 하나이며 label.ko/label.en이 필수입니다 |
| blocked_domains | body | array | 아니오 | — | 카테고리별 차단 도메인 패턴 배열(necessary 제외). FQDN 및 *. 와일드카드 prefix만 허용되며 textarea 줄바꿈 입력도 배열로 정규화됩니다 |
응답 필드 (data 내부)
에러 응답
| 상태코드 | 의미 | 발생 조건 |
|---|---|---|
| 401 | Unauthenticated | 유효한 Bearer 토큰이 없거나 만료된 경우 |
| 403 | Forbidden | 요구 권한(sirsoft-gdpr.privacy.update)이 없는 경우 |
| 422 | Unprocessable Entity | 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지) |
설명 검증된 GDPR 관리자 설정을 저장합니다. auth:sanctum과 sirsoft-gdpr.privacy.update 권한이 필요합니다. 설정만 저장할 뿐 정책 버전은 자동 발행되지 않으며, 재동의가 필요한 변경이라면 운영자가 「+ 새 버전 발행」을 별도로 눌러야 합니다. 배너 문구·위치, 쿠키 카테고리, 차단 도메인 등을 갱신하는 쓰기 엔드포인트입니다.
GET /api/plugins/sirsoft-gdpr/settings
- 라우트명:
api.plugins.sirsoft-gdpr.settings - 컨트롤러:
Plugins\Sirsoft\Gdpr\Http\Controllers\Public\GdprSettingsController@show - 인증/권한: 공개 (인증 불필요)
요청 파라미터
요청 파라미터 없음.
응답 필드 (data 내부)
단건 응답: data 객체의 필드.
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|---|---|---|---|
| cookie_policy_version | string | 10 |
현재 발행된 최신 정책 버전 문자열(gdpr_policy_versions 테이블이 SSoT, 최신 row의 version 정수). 게스트/회원 동의 시점 비교 및 배너 재노출 판정에 사용됩니다 |
| privacy_policy_slug | string | privacy |
개인정보 처리방침 페이지 slug. 설정이 비어 있으면 null로 반환됩니다 |
| privacy_policy_available | boolean | true |
처리방침 slug가 설정되어 링크 노출이 가능한지 여부. slug가 비면 false입니다 |
| legal_entity_name | string | `` | 개인정보 처리 법인/사업자명. 미설정 시 빈 문자열입니다 |
| data_storage_location | string | `` | 데이터 저장 위치 표기 문자열(국가 단위 안내). 미설정 시 빈 문자열입니다 |
| banner_enabled | boolean | true |
쿠키 배너와 자동 차단의 통합 활성 여부. true일 때만 게스트에게 배너가 노출되고 도메인 차단 엔진이 동작합니다 |
| banner_position | string | bottom_bar |
쿠키 배너 노출 위치(bottom_bar / bottom_left_popup / bottom_right_popup / centered_modal) |
| cookie_categories | array | [{"key":"necessary","required":true,"label":{"ko":"필수 쿠키"… |
배너·마이페이지 렌더링용 쿠키 카테고리 카탈로그 배열. 각 항목은 key, required(필수 여부), 다국어 label/description을 담습니다 |
| blocked_domains | object | {"functional":["*.crisp.chat","widget.intercom.io"],"anal… |
현재 설정된 카테고리별 차단 도메인 패턴(키→도메인 배열). 게스트도 차단이 동작해야 하므로 공개 응답에 노출되며 본 컨트롤러가 노출 SSoT입니다 |
| default_blocked_domains_preview | object | {"functional":["*.crisp.chat","client.crisp.chat","*.inte… |
플러그인 기본 차단 도메인 카탈로그 미리보기(변경 불가 기본값). 관리자가 커스텀 차단 목록을 편집할 때 참고용 기본 패턴을 보여줍니다 |
에러 응답
대표 에러 없음 (공개 조회).
설명 게스트도 접근할 수 있는 완전 공개 엔드포인트로, 인증 없이 호출됩니다. 공개 쿠키 동의 배너와 마이페이지 카드 렌더링에 필요한 쿠키 카테고리·배너 설정·차단 도메인과 현재 cookie_policy_version(정책 버전 서비스 기준)을 반환합니다. 차단 도메인은 게스트도 차단이 동작해야 하므로 공개 응답에 노출되며, 이 컨트롤러가 응답 노출의 기준(SSoT)입니다. 조회 전용입니다.