설명
인증이 필요한 API는 OpenAPI 3.0의 components.securitySchemes에 인증 방식을 정의해야 클라이언트가 필요한 헤더나 토큰을 알 수 있습니다. 인증 없이 제공하는 공개 API라면 이 정의를 생략할 수 있습니다.
잠재적 영향
필요한 인증 방식이 문서에서 빠지면 클라이언트 연동이 실패하거나 개발자가 권한 요구사항을 잘못 이해할 수 있습니다.
해결 방법
실제로 사용하는 인증 방식과 속성을 components.securitySchemes에 정의하고 전역 또는 작업별 security에서 참조하십시오. 서버와 게이트웨이도 같은 요구사항을 적용하도록 구성하십시오.
예시
예시는 인증이 필요한 API에 Bearer 인증 정의와 요구사항을 추가합니다. 서버에서 토큰을 검증하는 설정도 필요합니다.
변경 전
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "200 response"
}
}
}
}
}
}
변경 후
json
{
"openapi": "3.0.0",
"info": {
"title": "Simple API Overview",
"version": "1.0.0"
},
"paths": {
"/": {
"get": {
"responses": {
"200": {
"description": "200 response"
}
}
}
}
},
"security": [
{
"exampleSecurity": []
}
],
"components": {
"securitySchemes": {
"exampleSecurity": {
"type": "http",
"scheme": "bearer"
}
}
}
}