OpenMRS 프로젝트

이 페이지에는 Google Season of Docs에서 수락된 기술 작문 프로젝트의 세부정보가 포함되어 있습니다.

프로젝트 요약

오픈소스 조직:
OpenMRS
테크니컬 라이터:
사우라브
프로젝트 이름:
사용자 친화적인 REST API용 GitHub 문서 확장
프로젝트 기간:
표준 기간 (3개월)

Project description

기본 목표

OpenMRS Swagger 기반 REST API 문서를 개선하여 API 사용에 대한 지침을 추가합니다.

프로젝트 설명

OpenMRS REST API는 개발자가 OpenMRS의 데이터에 액세스하기 위한 핵심 메커니즘 중 하나입니다. OpenMRS Webservices API에 대한 Swagger 기반 자동 생성 문서와 정적 GitHub 기반 문서도 이미 있습니다. 이번 Docs 시즌에서는 GitHub 기반 문서를 확장해야 합니다.

간략한 개요

버크가 제안한 대로 OpenMRS Talk에 대한 약간의 조사를 통해 저는 이 프로젝트가 2017년에 GSOC 프로젝트로 시작되었다는 것을 알게 되었습니다. Gayan Weerakutti의 주요 목표는 OpenMRS REST API의 기존 문서를 개선하는 것이었고, Swagger 사양을 개선하고 Swagger 사양이 생성되는 방식을 개선하여 더 나은 버전의 swagger 문서 자체를 생성했습니다. 프로젝트에서 달성된 모든 관련 세부 사항은 이 OpenMRS 강연 게시물에 요약되어 있으며 매우 유용했습니다.

그런 다음 2019년에 이 프로젝트를 개편했고 Swagger 문서 수정사항에서 이를 변형하여 발전시켰습니다. 그 대신 GitHub에 적합한 정적인 문서를 개발해 이번 문서 시즌에 확장해 나갈 예정입니다.

따라서 현재 설명해야 할 프로젝트 제안의 요약은 다음과 같습니다.

  1. 많이 사용되는 언어 (특히 자바 및 자바스크립트)로 된 예제를 살펴봅니다.
  2. Swagger ''try-out'' 기능과 마찬가지로 슬레이트 문서에 플레이그라운드 지원을 추가합니다.
  3. 지금까지 완료된 작업을 리팩터링하고 개선합니다.
  4. 누락된 리소스 찾기 및 추가
  5. 문서의 콘솔 섹션에 좀 더 자세한 설명 추가

자세한 설명

  1. 다양한 언어로 예시를 생각해 보세요.

OpenMRS Android 클라이언트에서 작업하는 동안 REST API를 사용했고 Android용 엔드포인트를 사용하는 데 도움이 필요할 때마다 찾아볼 리소스가 없었기 때문에, SDK 기반 자바의 예를 추가한 다음 문서에 더 깊이 있는 재구성 예시를 추가하는 것이 좋습니다. JavaScript와 같은 다른 언어로 예시를 추가하는 것은 재구성 예시를 추가하는 것만큼 도움이 되지 않기 때문입니다. 그리고 Android 클라이언트에서 OpenMRS API 엔드포인트를 사용해 본 경험을 감안할 때 여기서 몇 가지 고품질의 예시를 만들 수 있을 것입니다. 이에 대해 멘토와 논의하고 결정 사항에 대해 작업하겠습니다. 또한 지원되는 작업에 대한 예제를 추가하는 것 외에도 일부 프로그래밍 언어에서 OpenMRS 서버로 인증하는 예제를 추가해야 합니다. 현재 이를 위한 curl 예만 있습니다.

  1. 테스트 API 예를 위한 플레이그라운드 지원 추가

데모 서버에 호스팅된 OpenMRS의 스웨거(swagger) 문서에서 이 기능을 사용했으며, 모든 API 문서에 있는 정말 편리한 도구입니다. 여기에서 약간 조사해 봤는데 Swagger-UI 사양을 현재 정적 문서에 포함하는 것은 그렇게 어렵지 않습니다. 표시 숨기기 전환을 사용하고 현재 swagger 문서 코드를 사용합니다. 이렇게 하면 시험 기능이 현재 API 사양에 맞춰 활성 상태로 유지되도록 할 수도 있습니다. 플레이그라운드 기능을 현재의 정적 문서에 통합할 수 있는 한 가지 방법이 될 것입니다.

  1. 지금까지 완료된 작업 리팩터링 및 개선
현재 curl 예시 확인

이 섹션은 올해 이 프로젝트에서 중점을 둔 부분 중 하나입니다. 현재 GitHub API 문서에 curl 예시만 있으며 이 중 일부는 브라우저에서 직접 확인하기 위해 데모 서버에서 직접 실행할 수 없습니다. 현재 엔드포인트를 모두 테스트하고 이러한 curl 요청을 실행할 때 얻은 다양한 curl 예시의 응답이 포함된 간단한 문서를 유지하겠습니다. 필요한 경우 swagger 문서에 내장된 테스트 기능과 함께 Postman을 사용하여 이 작업을 완료할 예정입니다.

일부 예시에서 API 응답이 누락되었습니다.

현재 curl 예에 대한 일부 응답이 추가되었지만 일부 curl 예에는 응답이 없습니다. 일반적으로 리소스 삭제와 같은 작업에서처럼 응답이 장황하지 않더라도 가능한 모든 응답 코드와 이를 얻는 이유를 문서화했지만 이렇게 하면 API 문서 전체의 예시가 더 균일해질 수 있다고 생각합니다.

다양한 연산에 대한 실제 사례 누락

이 부분이 API 문서에서 이전에 완수한 작업을 리팩터링하는 데 있어 가장 중요한 부분이라고 생각합니다. 문서에는 cURL로 직접 실행할 수 있는 구체적인 예시가 있습니다. 하지만 그중 일부는 다소 추상적인 내용이기 때문에 숙련된 개발자에게 좋은 참조가 되기는 하지만 신규 개발자는 골치 아픈 상태에 빠지게 됩니다. OpenMRS 강연의 이 게시물에서 좋은 예는 가치가 없다는 것을 알 수 있습니다. 따라서 작업 예시를 추가하는 것 외에도 실제로 별다른 작업이 아닌 구문 강조표시를 지원할 수 있습니다. 슬레이트와 함께 제공되어 여기에서 확인한 것처럼 쉽게 수행할 수 있습니다.

버크가 좋은 UI와 멋진 인터페이스 대신 문서에 단순성과 설명을 넣는 것을 여러 번 강조했듯이 저는 이러한 원칙을 준수하고, 현재 OpenMRS Webservices API를 작업 중인 개발자와 이야기하고 커뮤니티에 참여함으로써 이전에 문서화된 엔드포인트를 가능한 한 설명적으로 만들려고 노력할 것입니다. 저의 PR에서 명확하게 설명하지 않은 양식 리소스의 속성 유형에 대한 설명을 수집하기 위해 강연 게시물에서 한 것처럼. 멘토와 이야기를 나누고 문서에 실제로 가치를 더하고 가장 먼저 완수해야 할 일이 무엇인지 결정하면서 우선순위에 따라 업무를 처리할 것입니다.

사용 사례를 명시적인 제목으로 추가

많은 API 문서를 살펴봤는데 모든 사용 사례가 명시적인 헤드라인으로 되어 있음을 확인했습니다. 하지만 사용 사례가 명시적으로 보이지는 않지만 리소스 및 하위 리소스의 정의 뒤에 이어지는 정의와 예제 내에서 사용 사례가 다소 융합되어 있습니다. 개발자가 사용 사례를 단순히 검색할 필요 없이 문서에서 별도의 항목으로 분리하기 위해 노력해야 한다고 생각합니다.

  1. 누락된 리소스 찾기 및 문서화

    현재 프로젝트 상태에 리소스가 나열되어 있지만 여기에서 최신 버전의 swagger 문서를 살펴보면 GitHub 친화적인 API 문서에서 현재 리소스 모음에 추가할 수 있는 많은 리소스를 파악할 수 있습니다. 여기에는 Docs 2019 시즌 동안 다른 리소스와 함께 수행한 설명이 나와 있습니다. 문서에 추가해야 할 주제에 대해 논의하고 적절하게 추가하겠습니다.

결론

한동안 OpenMRS 커뮤니티에 참여했습니다. 서버와의 상호작용을 위해 API와 자주 상호작용하는 Android 클라이언트 프로젝트에 적극적으로 참여하고 있습니다. 따라서 저는 개발자로서 제 작업을 보고 다른 개발자의 작업이 정말 수월한지 평가할 수 있기 때문에 API 문서 확장 프로젝트를 꽤 잘 진행할 수 있다고 생각합니다. 저는 여기에 호스팅된 사용자 친화적인 문서 저장소에 사용되는 도구에 익숙해졌기 때문에 저장소와 도구에 익숙해지기 위해 이 저장소에도 여러 차례 기여했습니다.

커뮤니티의 피드백을 받는 데 도움이 되는 대담을 통해 매주 진행 상황을 전달하고 문서화 기간을 최대한 활용하기 위해 멘토 및 커뮤니티와 긴밀히 협력할 것입니다.