메뉴

Postman에서 API 문서를 만드는 방법은 무엇입니까?

  • 메인
  • 다른
  • Postman에서 API 문서를 만드는 방법은 무엇입니까?

how create api documentation postman

문제를 제거하기 위해 도구를 사용해보십시오

이 자습서에서는 Postman 도구에서 제공하는 API 문서 지원을 사용하여 최소한의 노력으로 멋진 스타일의 문서를 만드는 방법을 설명합니다.

내부 용이든 공개용이든 모든 API의 경우 문서는 성공을위한 가장 필수적인 요소 중 하나입니다.

그 주된 이유는 문서화가 사용자와 통신하는 방식입니다.

  • API를 어떻게 사용해야합니까?
  • 지원되는 모든 상태 코드는 무엇입니까?
  • 오류 코드는 무엇입니까?
  • 노출되는 모든 메소드 유형은 무엇입니까?

이 모든 정보는 누구나 원하는 필요에 따라 API를 사용하거나 구현하는 데 필요합니다.

=> 여기에서 간단한 우편 배달부 교육 시리즈를보십시오.

Postman-API 문서 생성

숙련 된 사람을위한 인터뷰 질문 및 답변 테스트

Postman은 사용하기 쉬운 문서화 방법론을 제공하며 기본 문서의 경우 Postman 컬렉션을 통해 버튼을 클릭하는 것만 큼 간단하며 API 문서에 대한 공개 URL을 얻을 수 있습니다.

학습 내용 :

Postman에서 API 문서 생성

문서 기능

Postman 문서 생성기의 두드러진 기능은 다음과 같습니다.

  • 마크 다운 구문을 지원합니다. Markdown은 일반적으로 Github 프로젝트에서 알아 차렸어야하는 일반적인 문서 구문입니다. 스타일 및 텍스트 서식을보다 친숙하고 쉽게 만들 수 있습니다.
  • 문서 작성을위한 특정 구문 / 요구 사항이 없습니다. 요청 및 수집 정보는 문서를 생성하는 가장 좋은 방법으로 활용됩니다.
  • 공용 URL 또는 사용자 지정 도메인 (엔터프라이즈 사용자 용)에 게시 할 수 있습니다.
  • C #, PHP, Ruby, Python, Node 등과 같은 다양한 언어로 API를 호출하기위한 코드 조각을 생성합니다.

문서 생성

Postman 문서 생성기는 컬렉션, 폴더 및 개별 요청 설명을 참조하고 컬렉션에 대한 문서를 생성하거나 생성하는 동안 수집합니다.

헤더, 쿼리 문자열 매개 변수, 양식 매개 변수와 같은 다양한 요청 매개 변수를 사용하고 요청 문서에서 이러한 값의 사용을 나타냅니다.

다음은 비디오 자습서입니다.

다른 문서와 동일한 테스트 API를 사용하여 3 개의 요청이있는 기본 컬렉션을 만들어 보겠습니다. 컬렉션 설명과 개별 요청에 몇 가지 정보를 추가하고 몇 가지 예제 요청 및 응답을 만들 것입니다. 이는 문서를 만드는 동안에도 캡처됩니다.

요청에 대한 기본 정보를 추가 한 다음 문서를 작성하려면 아래 단계를 따르십시오.

#1) 사용자 등록, 사용자 로그인 및 사용자 가져 오기 (참조 여기 요청 페이로드 및 API URL).

#두) 이제 마크 다운 형식의 정보를 컬렉션에 추가해 보겠습니다. Markdown은 Github의 거의 모든 문서에 사용되는 표준 형식입니다 (마크 다운에 대한 자세한 내용은 여기 ).

컬렉션 설명에 아래와 같은 마크 다운 형식으로 몇 가지 정보를 추가하겠습니다.

마크 다운 형식의 컬렉션 설명

마크 다운이 어떻게 보이는지 미리 보려면 오픈 소스 웹 포털을 참조하십시오. 여기.

마크 다운 문서

#삼) 이제 컬렉션의 개별 요청에 설명을 추가합니다. 컬렉션과 마찬가지로 요청 설명에 대해서도 마크 다운 형식이 지원됩니다 (마크 다운 가이드에 대한 자세한 내용은 여기 ).

사용자 등록 엔드 포인트에 대한 요청 중 하나의 샘플을 보겠습니다 (다른 요청에도 동일하게 적용될 수 있음).

마크 다운 텍스트 :

API endpoint to *Register* a user in the system. > A successful registration will result in a *HTTP 200* Status code

마크 다운 미리보기 :

마크 다운 미리보기

# 4) 모든 API 엔드 포인트에 대해 문서 생성기에서 사용할 예제를 캡처하거나 저장하겠습니다.

예는 고려할 API 요청에 대한 샘플 요청-응답 일뿐입니다. 응답을 예제로 저장하면 문서 생성기가이를 문서 자체의 일부로 캡처 할 수 있습니다.

예를 저장하려면 '보내다' 버튼을 눌러 요청을 실행하고 응답 탭에서 응답 저장-> 예제로 저장 .

예 저장

예제가 저장되면 컬렉션에 유지되며 나중에 언제든지 액세스 할 수 있습니다. 예 요청 빌더의 링크.

# 5) 위의 모든 정보가 추가되면 문서 미리보기를 만드는 방법을 살펴 보겠습니다.

컬렉션 옵션을 열고“ 문서 게시 ”.

문서 게시

노트 : 여기서 주목해야 할 중요한 점은 Postman에 등록 된 사용자 만 Postman에서 문서 게시 기능을 사용할 수 있다는 것입니다. 등록은 무료이지만 이메일 계정을 통해해야합니다. 등록 된 계정에 추가되는 컬렉션 및 작업 공간 공유, 모니터 생성 등과 같은 다른 기능 / 기능이 있습니다.

# 6) 한번 ' 문서 게시 ”이 실행되면 Postman 컬렉션 세부 정보가 포함 된 브라우저 탭이 열립니다 (내부적으로 Postman은 사용자의 로컬 파일 시스템뿐 아니라 자체 서버에이 컬렉션을 호스팅 함).

문서 컬렉션

클릭 '시사' 문서를 게시하기 전에 볼 수 있습니다.

' 컬렉션 게시 ”링크는 공개적으로 액세스 할 수있는 URL에 문서를 게시합니다. 공개 URL에 게시하기 위해 민감한 승인 정보가있는 API를 게시하는 것은 일반적으로 권장되지 않습니다. 이러한 API는 Postman의 엔터프라이즈 계정이있는 사용자 정의 도메인을 사용하여 게시 할 수 있습니다.

# 7) 문서 미리보기가 어떻게 보이는지 보겠습니다. “ 문서 미리보기 ”는 Postman의 서버에서 호스팅되는 미리보기 모드로 문서를 엽니 다. 문서에서 캡처 된 다른 세부 정보를 살펴 보겠습니다 (다른 위치에서 구성 했으므로 예를 들면 , 컬렉션 설명, 요청 설명 및 예).

Postman 문서 샘플

마크 다운에서 설명 요청

위의 2 개의 스크린 샷에서 컬렉션 및 요청 설명에 추가 된 모든 정보가 문서 미리보기에서 마크 다운 스타일 방식으로 캡처되었음을 확인할 수 있습니다.

C ++ 그래프 인접 목록

또한 문서는 기본적으로 강조 표시된대로 언어 바인딩을 제공하므로 나열된 언어로 API를 직접 요청하려는 사람이 훨씬 더 쉽게 할 수 있습니다.

# 8) 또한 배경색 변경, 헤더 템플릿의 배경 및 전경색 변경 등과 같은 매우 기본적인 스타일 수정을 수행 할 수 있습니다. 그러나 전반적으로 기본보기 자체는 많은 정보를 캡처하는 정말 좋은 문서 세트를 게시하기에 충분합니다. API에 대한 중요한 세부 정보입니다.

결론

이 튜토리얼에서는 최소한의 노력으로보기 좋은 스타일의 문서를 만들 수있는 Postman에서 제공하는 API 문서 지원을 살펴 보았습니다.

또한 생성 된 문서에 적용 할 수있는 많은 좋은 템플릿과 사용자 정의 스타일을 허용하고 공개 URL에 문서를 게시 할 수도 있습니다.

프라이빗 API 엔드 포인트의 경우 엔터프라이즈 계정 또는 사용자 용으로 구성 할 수있는 사용자 지정 도메인에 문서를 게시하는 조항도 있습니다.

추가 읽기 = >> Pact 중개인에게 Pact 계약을 게시하는 방법

=> 처음부터 우편 배달부를 배우려면 여기를 방문하십시오.

추천 도서

^