이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 구성:
- OpenMRS
- 기술 문서 작성자:
- Saurabh
- 프로젝트 이름:
- REST API를 위한 사용자 친화적인 GitHub 문서 확장
- 프로젝트 길이:
- 표준 기간 (3개월)
Project description
기본 목표
OpenMRS Swagger 기반 REST API 문서를 개선하여 API 사용에 대한 지침을 추가합니다.
프로젝트 설명
OpenMRS REST API는 개발자가 OpenMRS의 데이터에 액세스하는 주요 메커니즘 중 하나입니다. 이미 OpenMRS Webservices API에 관한 Swagger 기반 자동 생성 문서와 정적 GitHub 기반 문서가 있습니다. 이번 문서 시즌에서는 GitHub 기반 문서를 확장할 예정입니다.
개요
버크님이 제안한 대로 OpenMRS Talk에 대해 약간 조사한 결과 이 프로젝트가 2017년에 GSOC 프로젝트로 시작되었다는 사실을 알게 되었습니다. Gayan Weerakutti의 경우 주요 목표는 Swagger 사양을 개선하고 Swagger 사양이 생성되는 방식을 개선하여 더 나은 버전의 Swagger 문서 자체가 생성되도록 하여 OpenMRS REST API의 기존 문서를 개선하는 것이었습니다. 프로젝트에서 달성한 모든 관련 세부정보는 이 OpenMRS 대화 게시물에 요약되어 있으며 매우 유용했습니다.
2019년에 이 프로젝트가 개편되었으며, Swagger 문서 조정을 통해 다양한 버전을 만들었습니다. 대신 이번 Docs 시즌에 확장할 정적 GitHub 친화적인 문서를 개발했습니다.
설명하려는 현재 프로젝트 제안서의 개요는 다음과 같습니다.
- 일부 인기 언어 (특히 java 및 javascript)의 예를 들었습니다.
- Swagger ''try-out'' 기능과 같이 슬레이트 문서에 플레이그라운드 지원을 추가합니다.
- 지금까지 완료된 작업을 리팩터링하고 개선합니다.
- 누락된 리소스 찾기 및 추가
- 문서의 콘솔 섹션에 설명 추가
상세 설명
- 다양한 언어로 예시를 생각해 보세요.
SDK 기반의 Java 예시를 추가한 다음 문서에 더 많은 깊이를 더해 줄 수 있다고 생각하는 Retrofit 예시를 추가하는 것이 좋습니다. JavaScript와 같은 다른 언어로 예시를 추가하는 것은 Retrofit 예시를 추가하는 것만큼 도움이 되지 않습니다. OpenMRS Android 클라이언트를 작업하는 동안 이러한 REST API를 사용해 왔으며, 특히 Android용 엔드포인트를 사용할 때 도움이 필요할 때마다 참고할 수 있는 리소스가 없었기 때문입니다. Android 클라이언트에서 OpenMRS API 엔드포인트를 다루면서 얻은 경험을 바탕으로 여기에서 양질의 예시를 진지하게 만들 수 있습니다. 멘토와 논의한 후 결정된 사항을 처리하겠습니다. 또한 지원되는 작업의 예시를 추가하는 것 외에도 일부 프로그래밍 언어로 OpenMRS 서버에 인증하는 예시도 추가해야 합니다. 현재는 이에 대한 curl 예시만 있습니다.
- API 예시 테스트를 위한 플레이그라운드 지원 추가
데모 서버에서 호스팅되는 OpenMRS의 swagger 문서에서 이 기능을 사용한 적이 있으며, 모든 API 문서에 사용할 수 있는 정말 편리한 도구입니다. 여기에서 약간 조사해 보니 Swagger-UI 사양을 현재 정적 문서에 삽입하는 것은 그리 어렵지 않습니다. 표시 숨기기 전환 버튼을 사용하고 현재 swagger 문서 코드를 사용합니다. 이렇게 하면 현재 API 사양을 사용하여 체험판 기능을 계속 사용할 수 있습니다. 이는 플레이그라운드 기능을 현재 정적 문서에 통합하는 한 가지 방법입니다.
- 지금까지 완료된 작업을 리팩터링하고 개선함
현재 curl 예시 확인
이 섹션은 올해 이 프로젝트의 주요 강조사항 중 하나입니다. 현재 GitHub API 문서에는 curl 예시만 있으며, 그중 일부는 데모 서버에서 직접 실행하여 브라우저에서 직접 확인할 수 없습니다. 현재의 모든 엔드포인트를 테스트하고 이러한 curl 요청을 실행할 때 얻는 다양한 curl 예시 응답이 포함된 간단한 문서를 유지 관리하겠습니다. 필요한 경우 swagger 문서의 내장 체험판 기능 외에도 Postman을 사용하여 이 작업을 완료할 것입니다.
일부 예시에서 API 응답이 누락됨
현재 curl 예시에는 일부 응답이 추가되었지만, 일부 curl 예시에는 응답이 없습니다. 응답이 장황하지 않더라도(일반적으로 리소스 삭제와 같은 작업) JSON API 응답 예제가 있어야 합니다. 가능한 모든 응답 코드와 이 코드를 가져오는 이유를 문서화했습니다. 이렇게 하면 API 문서 전반에 걸쳐 예시가 더 균일해집니다.
다양한 작업에 관한 작동하는 예시가 누락됨
이는 API 문서에서 이전에 완료된 작업을 리팩터링하는 데 가장 중요한 부분이라고 생각합니다. 문서에는 cURL로 직접 실행할 수 있는 구체적인 예시가 있지만, 그중 일부는 약간 추상적이어서 경험 많은 개발자에게는 좋은 참고 자료가 되지만 초보자에게는 혼란을 줄 수 있습니다. OpenMRS 토크에서 이 게시물을 통해 좋은 예시가 얼마나 중요한지 알 수 있었습니다. 따라서 작업 예시를 추가하는 것 외에도 구문 강조 표시를 지원할 수 있습니다. 이는 실제로 별로 어렵지 않으며 슬레이트와 함께 제공되므로 여기에서 확인한 것처럼 쉽게 할 수 있습니다.
버크는 게시물에서 좋은 UI와 반짝이는 인터페이스 대신 문서의 단순성과 설명성을 선호한다고 여러 번 강조했습니다. 나는 이러한 원칙을 준수하고, 현재 OpenMRS Webservices API를 작업 중인 개발자와 대화하고 커뮤니티의 참여를 통해 이전에 문서화한 엔드포인트를 최대한 설명적으로 만들려고 합니다. 여기 PR에서 명확하지 않은 양식 리소스의 속성 유형에 대한 설명을 수집하는 강연 게시물에서 한 것처럼 말입니다. 우선순위에 따라 작업을 진행하고, 멘토와 상담하며, 문서에 가치를 더하고 먼저 완료해야 하는 작업을 결정합니다.
사용 사례를 명시적인 광고 제목으로 추가
API 문서를 이해하기 위해 여러 API 문서를 살펴본 결과, 모든 문서에 사용 사례가 명시적인 제목으로 표시되어 있었습니다. 사용 사례가 명시적으로 표시되지는 않지만 리소스 및 하위 리소스의 정의 뒤에 나오는 정의 및 예시 내에 다소 융합되어 있습니다. 개발자가 사용 사례를 추론하기 위해 정의를 검색하지 않고도 확인할 수 있도록 문서에서 사용 사례를 별도의 항목으로 구분하는 노력을 기울여야 한다고 생각합니다.
누락된 리소스 찾기 및 문서화
현재 프로젝트 상태에는 리소스가 나열되어 있지만 여기에서 최신 버전의 스와거 문서를 확인한 결과, GitHub 친화적인 API 문서의 현재 리소스 모음에 추가할 수 있는 많은 리소스를 확인할 수 있었습니다. 2019년 문서 시즌 동안 다른 리소스에 설명이 추가된 것처럼 설명을 추가할 수 있습니다. 문서에 추가해야 할 주제를 논의하고 적절하게 추가하겠습니다.
결론
저는 오랫동안 OpenMRS 커뮤니티에 참여해 왔습니다. 저는 Android 클라이언트 프로젝트에 적극적으로 참여하고 있으며, 이 프로젝트에서 API와 자주 상호작용하여 서버와 상호작용합니다. 따라서 저는 개발자로서 제 작업을 보고 다른 개발자의 작업을 정말로 쉽게 해 주는지를 평가할 수 있으므로 API 문서를 확장하는 이 프로젝트를 잘 진행할 수 있다고 생각합니다.여기에 호스팅된 사용자 친화적인 문서 저장소에 사용되는 도구에 익숙해졌으며 저장소 및 도구(예: slateUI)에 익숙해지기 위해 이 저장소에 여러 가지 기여도 했습니다. API는 문서만큼 좋다고 생각되므로 문서를 개선하여 OpenMRS Rest API를 조금 더 개선하고 싶습니다.
커뮤니티의 의견을 얻고 멘토 및 커뮤니티와 긴밀하게 협력하여 문서화 기간을 최대한 활용할 수 있도록 매주 진행 상황을 토크 게시물로 전달하겠습니다.