이 페이지에는 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 사양이 생성되는 방식을 개선하여 더 나은 버전의 문서가 생성되도록 했습니다. 이 프로젝트에서 달성한 모든 관련 세부사항은 이 OpenMRS 대화 게시물에 요약되어 있으며 상당히 유용했습니다.
그런 다음 2019년에 이 프로젝트를 개편했고, Swagger 문서 수정을 거쳐 이에 대한 변형을 만들어냈습니다. 우리는 그 대신 정적인 GitHub 친화적인 문서를 개발했으며 이번 Docs 시즌에 확장할 예정입니다.
따라서 현재 제가 설명하고자 하는 프로젝트 제안은 다음과 같습니다.
- 많이 사용되는 언어 (특히 자바와 자바스크립트)로 예시 만들기
- Swagger ''try-out'' 기능과 같이 슬레이트 문서에 플레이그라운드 지원을 추가합니다.
- 지금까지 완료된 작업을 리팩터링하고 개선합니다.
- 누락된 리소스 찾기 및 추가
- 문서의 콘솔 섹션에 좀 더 자세한 설명 추가
자세한 설명
- 다양한 언어로 예시를 생각해 보세요.
OpenMRS Android 클라이언트에서 작업하는 동안 REST API를 사용했고 특별히 Android용 엔드포인트를 사용하는 데 도움이 필요할 때마다 찾아볼 리소스가 없었기 때문에, JavaScript와 같은 다른 언어로 예시를 추가하는 것만큼 도움이 되지 않을 것이므로 Java에서 SDK 기반 예시를 추가한 후 Retrofit 예시를 추가하는 것이 좋습니다. 그리고 Android 클라이언트에서 OpenMRS API 엔드포인트를 조작한 경험을 고려하면 여기서 몇 가지 품질의 예를 진지하게 만들 수 있을 것입니다. 이에 대해 멘토와 논의하고 결정되는 대로 작업할 예정입니다. 또한 지원되는 연산의 예를 추가하는 것 외에도 일부 프로그래밍 언어의 OpenMRS 서버로 인증하는 방법에 대한 예시도 추가해야 합니다. 현재는 이에 대한 curl 예만 있습니다.
- 테스트 API 예시를 위한 플레이그라운드 지원 추가
데모 서버에 호스팅된 OpenMRS의 대규모 문서에서도 이 기능을 사용해 봤는데, 모든 API 문서에 포함할 수 있는 정말 편리한 도구입니다. 여기에서 약간 조사했으며 현재 정적 문서에 Swagger-UI 사양을 삽입하는 것은 그리 어렵지 않습니다. 숨기기 전환 표시와 현재 swagger 문서 코드 사용 이렇게 하면 시험용 기능이 현재 API 사양에 맞춰 활성 상태로 유지되도록 할 수도 있습니다. 이것이 플레이그라운드 기능을 현재 정적 문서에 통합할 수 있는 한 가지 방법입니다.
- 지금까지 완료된 작업 리팩터링 및 개선
현재 curl 예 확인하기
이 섹션은 올해 이 프로젝트에서 중점을 둔 부분 중 하나입니다. 현재 GitHub API 문서에 curl 예시만 나와 있으며 이 중 일부는 브라우저에서 직접 확인하기 위해 데모 서버에서 직접 실행할 수 없습니다. 현재의 모든 엔드포인트를 테스트하고, curl 요청을 실행할 때 얻는 다양한 curl 예시의 응답이 포함된 간단한 문서를 유지하겠습니다. 필요한 경우 swagger 문서에 내장된 무료 체험판 기능과 함께 Postman을 사용하여 이 작업을 수행하겠습니다.
일부 예시에서 API 응답이 누락됨
현재 curl 예에 대한 일부 응답이 추가되었지만 일부 curl 예에는 응답이 없습니다. 일반적으로 리소스 삭제와 같은 작업에서처럼 응답이 장황하지 않더라도 가능한 모든 응답 코드와 이를 얻는 이유는 문서화했지만, 이렇게 하면 API 문서의 예시가 더 균일해질 수 있다고 생각합니다.
다양한 연산에 대한 실제 예시 누락
이것이 API 문서에서 이전에 완수한 작업을 리팩터링하는 데 있어 가장 중요한 부분이라고 생각합니다. 문서에는 cURL로 직접 실행할 수 있는 구체적인 예시가 있지만, 그중 일부는 숙련된 개발자에게 좋은 참고 자료로 주지만 신규 개발자에게는 신경 쓰게 하는 다소 추상적인 사례입니다. OpenMRS 대담의 이 게시물에서 좋은 예에는 가치가 없다는 것을 알 수 있습니다. 따라서 작업 예시를 추가하는 것 외에도, 작업 예시가 많지 않은 구문 강조 표시를 지원할 수 있을 뿐 아니라 슬레이트와 함께 제공되어 이 작업을 쉽게 수행할 수 있습니다.
버크는 좋은 UI와 화려한 인터페이스 대신 문서에서 단순성과 설명을 선호한다는 것을 여러 번 강조하였으며, PR에서 명확하게 드러나지 않은 양식 리소스의 속성 유형에 대한 설명을 수집하는 토크 게시물에서와 마찬가지로 현재 OpenMRS Webservices API를 사용하는 개발자와 대화하고 커뮤니티에 참여함으로써 이전에 문서화된 엔드포인트를 가능한 한 설명하려고 노력할 것입니다. 멘토와 이야기를 나누고 문서에 정말로 가치를 더하고 가장 먼저 완수해야 할 일을 결정하며 우선순위에 따라 업무를 처리할 것입니다.
사용 사례를 명시적인 제목으로 추가
사용법을 익히기 위해 많은 API 문서를 살펴봤는데 모두 명확한 제목으로 사용 사례가 있음을 확인했습니다. 그러나 사용 사례가 명시적으로 보이지는 않지만 리소스와 하위 리소스의 정의에 따라 정의 및 예시에 다소 통합되어 있으므로 개발자가 사용 사례를 검색하지 않고 직접 찾아볼 수 있도록 문서에서 별도의 항목으로 분리하기 위해 노력해야 합니다.
누락된 리소스 찾기 및 문서화
현재 프로젝트 상태에 리소스 목록이 나와 있지만, 여기에서 최신 버전의 리소스를 살펴보면 GitHub 친화적인 API 문서의 현재 리소스 모음에 추가할 수 있는 많은 리소스를 파악할 수 있습니다. 문서 2019 시즌 동안 다른 리소스에서 얻은 설명과 함께 설명도 포함되어 있습니다. 문서에 추가해야 하는 주제에 관해 논의하고 적절하게 추가합니다.
결론
한동안 OpenMRS 커뮤니티에 참여했습니다. 서버와 상호작용하기 위해 자주 API와 상호작용하는 Android 클라이언트 프로젝트에 적극적으로 참여하고 있습니다. 따라서 저는 개발자로서 제 작업을 직접 보고 다른 개발자의 작업이 정말 쉬워졌는지 평가할 수 있기 때문에 API 문서 확장 프로젝트를 훌륭하게 진행할 수 있다고 생각합니다. 저는 여기에서 호스팅되는 사용자 친화적인 문서 저장소에 사용되는 도구에 익숙해졌기 때문에 이 저장소에도 여러 차례 기여했습니다.
커뮤니티의 피드백을 받고 멘토 및 커뮤니티와 긴밀히 협력하여 이번 문서 기간을 최대한 활용할 수 있도록 토크 게시물을 통해 매주 진행 상황을 전달하겠습니다.