공통 항목

OpenAPI 2.0과 3.0의 공통 보안 설정, 파라미터, 응답, 스키마와 참조 관련 문서입니다.

문서 목록

문서 경로
DELETE 성공 응답 미정의 (OpenAPI 3.0) openAPI/general/success_response_code_undefined_delete_operation
GET 성공 응답 미정의 (OpenAPI 3.0) openAPI/general/success_response_code_undefined_get_operation
HEAD 성공 응답 미정의 (OpenAPI 3.0) openAPI/general/success_response_code_undefined_head_operation
JSON Object Schema에 Properties 없음 openAPI/general/json_object_schema_without_properties
JSON Object Schema에 Type 없음 openAPI/general/json_object_schema_without_type
PATCH 성공 응답 미정의 (OpenAPI 3.0) openAPI/general/success_response_code_undefined_patch_operation
POST 성공 응답 미정의 (OpenAPI 3.0) openAPI/general/success_response_code_undefined_post_operation
PUT 성공 응답 미정의 (OpenAPI 3.0) openAPI/general/success_response_code_undefined_put_operation
Schema Object 비어 있음 openAPI/general/schema_object_empty
참조 객체의 추가 속성 점검 openAPI/general/json_ref_alongside_properties
OpenAPI 연락처 URL 점검 openAPI/general/invalid_contact_url
OpenAPI 연락처 이메일 점검 openAPI/general/invalid_contact_email
기본값과 타입 불일치 (OpenAPI 3.0) openAPI/general/default_invalid
enum과 추가 스키마 제약 점검 openAPI/general/object_using_enum_with_keyword
예시 값과 스키마 타입 불일치 (OpenAPI 3.0) openAPI/general/example_not_compliant_with_schema_type
Accept 헤더 파라미터 정의 점검 openAPI/general/header_parameter_named_as_accept
Authorization 헤더 파라미터 정의 점검 openAPI/general/header_parameter_named_as_authorization
Content-Type 헤더 파라미터 정의 점검 openAPI/general/header_parameter_named_as_content_type
OpenAPI 라이선스 URL 점검 openAPI/general/invalid_license_url
스키마의 최소·최대 범위 역전 openAPI/general/property_defining_maximum_not_greater_than_minimum
작업별 외부 문서 URL 점검 openAPI/general/invalid_operation_external_documentation_url
필수 속성의 스키마 정의 점검 openAPI/general/properties_missing_required_property
응답 헤더 정의와 HTTP 의미 점검 openAPI/general/header_response_name_is_invalid
스키마 외부 문서 URL 점검 openAPI/general/invalid_schema_external_documentation_url
태그 외부 문서 URL 점검 openAPI/general/invalid_tag_external_documentation_url
경로 변수에 대응하는 path 파라미터 누락 openAPI/general/template_path_parameter_with_no_corresponding_path_parameter
경로 템플릿과 맞지 않는 경로 파라미터 openAPI/general/path_parameter_with_no_corresponding_template_path
모호한 경로 정의 openAPI/general/path_ambiguous
문자열 패턴 미정의 (OpenAPI 3.0) openAPI/general/pattern_undefined
문자열 최대 길이 미정의 (OpenAPI 3.0) openAPI/general/maximum_length_undefined
문자열 패턴의 허용 범위가 지나치게 넓음 (OpenAPI 3.0) openAPI/general/string_schema_with_broad_pattern
discriminator 값의 타입과 매핑 점검 openAPI/general/schema_discriminator_property_not_string
배열 스키마에 최대 개수 제한 없음 openAPI/general/array_without_maximum_number_items
배열 항목 정의 누락 openAPI/general/items_undefined
배열 항목 타입 미정의 (OpenAPI 3.0) openAPI/general/array_items_has_no_type
본문이 없는 응답에 본문 정의 (OpenAPI 3.0) openAPI/general/response_operations_body_schema_incorrect_defined
스키마 타입과 items 용도 점검 openAPI/general/non_array_schema_with_items
비어 있는 작업별 security 배열 openAPI/general/security_operations_empty_array
OpenAPI paths의 경로 공개 범위 점검 openAPI/general/paths_object_empty
OpenAPI 응답 정의 점검 openAPI/general/responses_object_is_empty
비어 있는 전역 security 배열 openAPI/general/security_empty_array
작업별 security의 빈 객체 openAPI/general/security_operations_empty_object_definition
전역 security의 빈 객체 openAPI/general/security_empty_object_definition
이름이 비어 있는 경로 자리표시자 openAPI/general/path_template_empty
작업의 정상 응답 정의 점검 openAPI/general/operation_without_successful_http_status_code
discriminator 속성 정의 점검 openAPI/general/schema_discriminator_mismatch_defined_properties
숫자 형식 미지정 (OpenAPI 3.0) openAPI/general/numeric_schema_without_format
숫자 최댓값 미정의 (OpenAPI 3.0) openAPI/general/numeric_schema_without_maximum
숫자 최솟값 미정의 (OpenAPI 3.0) openAPI/general/numeric_schema_without_minimum
응답 본문 Schema 없음 openAPI/general/response_operations_body_schema_undefined
스키마 조합의 직접 자기 참조 점검 openAPI/general/schema_object_with_circular_ref
default 응답 미정의 (OpenAPI 3.0) openAPI/general/default_response_undefined_operations
작업별 API 키 인증의 전송 보안 점검 (OpenAPI 3.0) openAPI/general/api_key_exposed_in_operation_security
OpenAPI 경로의 작업 공개 범위 점검 openAPI/general/path_without_operation
잘못된 HTTP 응답 상태 코드 openAPI/general/responses_wrong_http_status_code
잘못된 위치에서의 allowEmptyValue 사용 openAPI/general/property_allow_empty_value_improperly_defined
전역 외부 문서 URL 점검 openAPI/general/invalid_global_external_documentation_url
전역 인증 요구사항이 없는 OpenAPI 문서 openAPI/general/global_security_field_undefined
인증 요구사항이 선언되지 않은 OpenAPI 작업 openAPI/general/no_global_and_operation_security_defined
전역 API 키 인증의 전송 보안 점검 (OpenAPI 3.0) openAPI/general/api_key_exposed_in_global_security
필수 속성의 타입 정의 점검 openAPI/general/schema_required_property_undefined
중복된 operationId 사용 openAPI/general/operation_id_not_unique
조합 스키마의 속성 제약 점검 openAPI/general/schema_object_properties_with_duplicated_keys
파라미터 식별 조합과 사용 위치 점검 openAPI/general/parameters_name_in_not_unique
헤더 파라미터 이름 중복 점검 openAPI/general/parameter_objects_headers_dup_name
enum 값과 스키마 타입의 일치 점검 openAPI/general/schema_enum_invalid
타입과 맞지 않는 숫자 형식 (OpenAPI 3.0) openAPI/general/invalid_format
스키마 타입별 제약 적용 점검 openAPI/general/type_has_invalid_keyword
필수 속성과 기본값의 동작 점검 openAPI/general/required_property_default_value
예상 응답 코드 누락 (OpenAPI 3.0) openAPI/general/response_code_missing
필수 지정이 없는 discriminator 속성 openAPI/general/schema_discriminator_not_required
필수 지정이 없는 경로 파라미터 openAPI/general/path_parameter_not_required

관련 문서72

DELETE 성공 응답 미정의 (OpenAPI 3.0)

삭제 요청의 성공 결과가 OpenAPI 응답 정의에 없는 경우

GET 성공 응답 미정의 (OpenAPI 3.0)

조회 성공 시 반환하는 상태 코드가 문서에 없는 경우

HEAD 성공 응답 미정의 (OpenAPI 3.0)

본문 없이 메타데이터를 조회하는 HEAD의 성공 응답이 없는 경우

JSON Object Schema에 Properties 없음

필드 구성이 정해진 객체는 properties로 각 필드를 정의합니다.

JSON Object Schema에 Type 없음

객체만 허용하려는 스키마에는 객체 타입 제약을 명시합니다.

PATCH 성공 응답 미정의 (OpenAPI 3.0)

리소스 부분 수정의 성공 결과가 문서에 없는 경우

POST 성공 응답 미정의 (OpenAPI 3.0)

생성이나 처리 요청의 성공 결과가 문서에 없는 경우

PUT 성공 응답 미정의 (OpenAPI 3.0)

리소스 생성 또는 교체의 성공 응답이 없는 경우

Schema Object 비어 있음

데이터 구조를 제한해야 한다면 빈 스키마에 필요한 제약을 정의합니다.

참조 객체의 추가 속성 점검

참조 객체 옆에 쓴 제약이 실제로 적용되는지 명세 버전에 맞춰 확인하세요.

OpenAPI 연락처 URL 점검

연락처 링크가 올바른 지원 페이지로 연결되는지 확인하세요.

OpenAPI 연락처 이메일 점검

연락처의 표기와 실제 수신 가능 여부를 확인하세요.

기본값과 타입 불일치 (OpenAPI 3.0)

default 값이 선언된 데이터 타입과 맞지 않는 경우

enum과 추가 스키마 제약 점검

열거값과 다른 스키마 제약을 함께 검토해 실제 허용값을 명확히 하세요.

예시 값과 스키마 타입 불일치 (OpenAPI 3.0)

문서의 예시 값이 연결된 스키마와 다른 타입을 사용하는 경우

Accept 헤더 파라미터 정의 점검

응답 형식 협상을 일반 입력 파라미터와 구분하세요.

Authorization 헤더 파라미터 정의 점검

인증 요구 사항을 보안 스킴으로 표현하세요.

Content-Type 헤더 파라미터 정의 점검

요청 본문의 미디어 타입을 해당 본문 정의에 명시하세요.

OpenAPI 라이선스 URL 점검

라이선스 링크가 올바른 조건 문서로 연결되는지 확인하세요.

스키마의 최소·최대 범위 역전

숫자, 문자열 길이와 배열 크기의 최솟값이 최댓값을 넘지 않도록 정의하세요.

작업별 외부 문서 URL 점검

작업의 상세 가이드가 올바른 링크로 연결되는지 확인하세요.

필수 속성의 스키마 정의 점검

필수 속성의 존재 조건과 형식 제약을 구분하고 실제 API 계약에 맞게 정의하세요.

응답 헤더 정의와 HTTP 의미 점검

응답 형식과 실제 응답 헤더를 구분해 문서화하세요.

스키마 외부 문서 URL 점검

데이터 모델의 추가 설명을 올바른 문서에 연결하세요.

태그 외부 문서 URL 점검

태그별 외부 문서 링크가 의도한 안내 자료를 가리키는지 확인하세요.

경로 변수에 대응하는 path 파라미터 누락

경로 변수와 같은 이름의 필수 path 파라미터를 경로 또는 작업 수준에 정의하세요.

경로 템플릿과 맞지 않는 경로 파라미터

경로 파라미터는 경로 템플릿의 같은 이름의 자리표시자에 대응해야 합니다.

모호한 경로 정의

변수 이름만 다른 동일 경로 패턴을 구분되는 엔드포인트로 선언하지 마세요.

문자열 패턴 미정의 (OpenAPI 3.0)

형식이 정해진 문자열에 필요한 패턴 제약이 없는 경우

문자열 최대 길이 미정의 (OpenAPI 3.0)

길이 제한이 필요한 문자열에 maxLength가 없는 경우

문자열 패턴의 허용 범위가 지나치게 넓음 (OpenAPI 3.0)

문자열 패턴이 실제로 허용하려는 형식을 충분히 제한하지 못하는 경우

discriminator 값의 타입과 매핑 점검

타입 구분자 값과 스키마 매핑을 일치시키고 도구의 문자열 변환에 의존하는지 확인하세요.

배열 스키마에 최대 개수 제한 없음

항목 수에 한도가 필요한 배열은 maxItems로 최대 개수를 명시합니다.

배열 항목 정의 누락

배열 타입 스키마나 파라미터에는 해당 버전에 맞는 items 정의가 필요합니다.

배열 항목 타입 미정의 (OpenAPI 3.0)

특정 타입을 기대하는 배열에서 항목 스키마가 타입을 제한하지 않는 경우

본문이 없는 응답에 본문 정의 (OpenAPI 3.0)

HEAD, 204 또는 304 응답의 본문 정의가 HTTP 의미와 충돌하는 경우

스키마 타입과 items 용도 점검

items를 실제 배열 요소의 제약으로 사용하고 데이터 타입과 맞추세요.

비어 있는 작업별 security 배열

작업별 security가 빈 배열이면 해당 작업은 전역 인증 요구사항을 상속하지 않습니다.

OpenAPI paths의 경로 공개 범위 점검

빈 paths가 의도한 공개 범위를 반영하는지 확인하고 필요한 경로를 문서화하세요.

OpenAPI 응답 정의 점검

각 작업의 responses에 실제 응답을 하나 이상 정의하세요.

비어 있는 전역 security 배열

전역 security가 빈 배열이면 기본 인증 요구사항이 없습니다.

작업별 security의 빈 객체

작업별 security의 빈 요구사항과 잘못된 객체 형식을 구분하고 의도한 인증 정책을 지정하세요.

전역 security의 빈 객체

전역 security 배열의 빈 요구사항 객체는 인증 없는 접근을 허용하는 선택지가 됩니다.

이름이 비어 있는 경로 자리표시자

경로 템플릿의 자리표시자에 이름을 지정하고 같은 이름의 필수 파라미터를 정의하세요.

작업의 정상 응답 정의 점검

작업이 실제로 반환하는 정상 처리 결과를 문서에 명확히 나타내세요.

discriminator 속성 정의 점검

타입 구분에 사용하는 속성 이름과 실제 스키마 정의를 일치시키세요.

숫자 형식 미지정 (OpenAPI 3.0)

숫자의 표현 방식을 나타내는 format이 지정되지 않은 경우

숫자 최댓값 미정의 (OpenAPI 3.0)

상한이 필요한 숫자 필드에 maximum 제약이 없는 경우

숫자 최솟값 미정의 (OpenAPI 3.0)

하한이 필요한 숫자 필드에 minimum 제약이 없는 경우

응답 본문 Schema 없음

실제로 본문을 반환하는 응답은 미디어 유형과 데이터 구조를 문서화합니다.