[api] REST API에 대한 온라인 문서 구조화

Program / 글쓴이

데이터를 JSON 및 XML 형식으로 직렬화하는 첫 번째 Rest API를 구축하고 있습니다. 구현 된 엔드 포인트를 선택할 수있는 API 클라이언트에 색인 페이지를 제공하고 싶습니다.

API를 가장 유용하게 만들려면 어떤 정보를 포함해야하며 어떻게 구성해야합니까?

답변

간단한 대답으로는 매우 복잡한 질문입니다.

Swagger Specification ( OpenAPI ) 과 같은 기존 API 프레임 워크 와 apiary.io 및 apiblueprint.org 와 같은 서비스 를 살펴볼 수 있습니다.

또한 다음은 세 가지 다른 방식으로 설명, 구성 및 스타일이 지정된 동일한 REST API의 예입니다. 기존의 일반적인 방법에서 배우는 것이 좋은 시작일 수 있습니다.

최상위 수준에서 고품질 REST API 문서에는 최소한 다음이 필요하다고 생각합니다.

  • 모든 API 엔드 포인트 목록 (기본 / 상대 URL)
  • 각 엔드 포인트에 해당하는 HTTP GET / POST / … 메소드 유형
  • 요청 / 응답 MIME 유형 (매개 변수를 인코딩하고 응답을 구문 분석하는 방법)
  • HTTP 헤더를 포함한 샘플 요청 / 응답
  • URL, 본문 및 헤더의 매개 변수를 포함하여 모든 매개 변수에 대해 지정된 유형 및 형식
  • 간단한 텍스트 설명 및 중요 참고 사항
  • 널리 사용되는 웹 프로그래밍 언어에서 엔드 포인트 사용을 보여주는 짧은 코드 스 니펫

또한 API 정의 또는 스키마를 구문 분석하고 편리한 문서 세트를 생성 할 수있는 많은 JSON / XML 기반 문서 프레임 워크가 있습니다. 그러나 문서 생성 시스템의 선택은 프로젝트, 언어, 개발 환경 및 기타 많은 사항에 따라 다릅니다.

답변