Setting : 스웨거 api-doc 상단 링크 추가 #219
Conversation
K-KY
requested review from
Eseas,
taekminKwon,
kdh10806,
HiSeungmin and
jeongns2611
as code owners
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| } |
There was a problem hiding this comment.
코드 리뷰 결과는 다음과 같습니다.
-
문서화 추가:
@Info어노테이션을 사용하여 API 문서의 설명, 제목 및 버전을 추가한 것은 좋습니다. 이는 API 사용자에게 유용한 정보를 제공하는 데 도움이 됩니다. -
코드 정리:
@OpenAPIDefinition의 형식을 잘 정리해주셨습니다. 가독성이 향상되었습니다. -
서버 URL: 서버 URL이
localhost와https://api.devlens.work/admin으로 설정되어 있는데, 배포 환경에 따라localhostURL은 프로덕션 코드에 포함되지 않도록 주의해야 합니다. 이 부분에 대한 주석이나 구성 변경 필요성이 있을 수 있습니다. -
예외 처리: API 문서화와 관련하여 예외 처리나 응답 형식에 대한 구체적인 설명도 포함하는 것이 좋습니다. 향후 이 작업이 필요하면 이러한 내용을 문서에 추가하는 것을 고려하세요.
-
코드 스타일: 파일 끝에 새 줄이 없는 점은 일반적으로 권장되지 않습니다. 파일의 마지막에 항상 새 줄을 추가하면 나중에 코드 통합이나 툴 사용 시 문제가 발생하지 않습니다.
-
문서화 언어: 문서 제목과 설명이 한국어로 작성되어 있는데, 이 API가 사용될 사용자나 팀에 맞게 선택하시고, 필요에 따라 영어 버전도 작성을 고려할 수 있습니다.
전반적으로 코드는 잘 작성되었으며, 가독성과 문서화의 유용성이 증가했습니다. 위의 점들을 고려하여 추가적인 개선점을 반영하면 더욱 견고한 코드가 될 것입니다.
| description = "Devlens Admin API 문서", | ||
| title = "Devlens Admin API 문서", | ||
| version = "1.0" | ||
| ), | ||
| servers = { | ||
| @Server(description = "local Port Main", url = "http://localhost:8444"), | ||
| @Server(description = "server Main", url = "https://api.devlens.work/main") |
There was a problem hiding this comment.
코드 패치에 대한 간단한 리뷰를 제공하겠습니다.
주요 변경사항
OpenAPIDefinition에Info주석을 추가하여 API 문서에 대한 설명, 제목 및 버전을 명시했습니다.
코드 리뷰
긍정적인 점
- API 문서화 정보가 추가되어 Swagger UI에서의 가독성이 향상되었습니다.
- API 설명이 포함되어 있어 사용자가 API의 목적을 쉽게 이해할 수 있습니다.
개선 사항 및 버그 위험
-
버전 관리:
"1.0"버전 명명 규칙은 괜찮지만, 이후 업데이트를 고려할 때 적절한 버전 관리 전략을 준비하는 것이 좋습니다. 예를 들어, 다음 버전에서2.0형태로 업데이트할 경우, 대문자에 따른 변경이 필요한지 검토해야 합니다.
-
서버 URL:
- 로컬 환경과 실환경의 URL을 직접 코드에 하드코딩하는 것은 좋은 방법이 아닙니다. 환경에 따라 동적으로 URL을 설정할 수 있는 방법(예: 프로퍼티 파일이나 환경 변수를 사용하는 방식)을 고려해 보세요. 이는 배포 시 설정 변경을 용이하게 합니다.
-
API 문서에 대한 추가 정보:
- API 문서에 대한 추가 정보가 고려될 수 있습니다. 예를 들어, API나 서비스의 다루는 특정 기능이나 사용 예제를 간략히 설명하는 섹션을 추가하는 것이 좋습니다. 이는 사용자에게 보다 유용한 정보를 제공할 수 있습니다.
-
주석 및 문서화:
- 주석을 추가하여 각 주석의 의미와 사용례를 설명하는 것이 좋습니다. 개발 중에 혼동을 줄이고, 팀원들이 쉽게 이해할 수 있도록 도와줄 수 있습니다.
이와 같은 개선 사항을 고려하면 코드의 품질과 유지 보수성이 향상될 것입니다.
No description provided.