REST API의 문서화를 자동화하는 방법 (Jersey 구현)

REST API의 문서화를 자동화하는 방법 (Jersey 구현)

---

Java Jersey (및 JAXB)를 사용하여 매우 광범위한 REST API를 작성했습니다. 나는 또한 위키를 사용하여 문서를 작성했지만, 그것은 완전히 수동적 인 프로세스 였고, 특히 우리가 수정해야 할 때, 사람들은 위키를 업데이트하는 것을 잊는 경향이 있습니다.

주변을 둘러 보면 대부분의 다른 REST API도 수동으로 문서를 작성합니다. 그러나 이것에 대한 좋은 해결책이 있는지 궁금합니다.

각 엔드 포인트에 대해 문서화해야하는 종류는 다음과 같습니다.

• 작업 명
• 범주
• URI
• 매개 변수
• 매개 변수 유형
• 응답 유형
• 응답 유형 스키마 (XSD)
• 샘플 요청 및 응답
• 요청 유형 (Get / Put / Post / Delete)
• 기술
• 반환 될 수있는 오류 코드

그리고 물론 다음과 같은 글로벌 한 몇 가지 일반적인 것들이 있습니다.

• 보안
• REST 개요
• 오류 처리
• 기타

이러한 일반적인 사항은 한 번만 설명해도 좋고 자동화 할 필요는 없지만 웹 서비스 메서드 자체의 경우 자동화하는 것이 매우 바람직합니다.

어노테이션을 사용하고 XML을 생성하는 작은 프로그램을 작성한 다음 실제 문서를 HTML로 생성해야하는 XSLT를 작성하는 방법을 생각했습니다. 사용자 정의 XDoclet을 사용하는 것이 더 합리적입니까?

---

Swagger 는 아름다운 옵션입니다. GitHub의 프로젝트이며 Maven 통합 및 유연성을 유지하는 다른 옵션이 있습니다.

통합 가이드 : https://github.com/swagger-api/swagger-core/wiki

추가 정보 : http://swagger.io/

---

불행히도 Darrel의 대답은 기술적으로 정확하지만 현실 세계에서는 요점입니다. 그것은 오직 일부만이 동의하는 이상에 기반을두고 있으며 당신이 그것에 대해 매우 조심 했더라도 어떤 이유로 든 당신이 통제 할 수없는 이유 때문에 정확하게 따를 수 없을 가능성이 있습니다.

가능하더라도 API를 사용해야하는 다른 개발자는 RESTful 패턴의 세부 사항을 신경 쓰지 않거나 알지 못할 수 있습니다. API를 만드는 요점은 다른 사람들이 쉽게 사용할 수 있도록하는 것이며 좋은 문서는 절대로 필요한 것.

그러나 WADL에 대한 Achim의 요점은 좋습니다. 존재하기 때문에 API 문서를 생성하기위한 기본 도구를 만들 수 있어야합니다.

일부 사람들은이 경로를 택했으며 변환을 수행하기 위해 XSL 스타일 시트가 개발되었습니다. https://wadl.dev.java.net/

---

그것이 당신의 요구에 완전히 맞을지는 모르겠지만 enunciate를 살펴보십시오 . 다양한 웹 서비스 아키텍처를위한 좋은 문서 생성기처럼 보입니다.

EDIT Enunciate는 github 우산 아래에서 사용할 수 있습니다.

---

런타임시 XML 형식으로 게시 된 모든 리소스에 대해 소위 WADL 설명 을 제공하는 Jersey의 기능에 관심이있을 수 있습니다 (주석에서 자동으로 생성됨). 여기에는 기본 문서에 필요한 내용이 이미 포함되어 있어야합니다. 더 많은 구성이 필요하지만 추가 JavaDoc을 추가 할 수 있습니다.

여기를보세요 : https://jersey.java.net/documentation/latest/wadl.html

---

Darrel의 대답은 정확히 맞습니다. 클라이언트 개발자가 클라이언트 구현을 서비스의 현재 구현에 연결하게하므로 REST API의 클라이언트에게 설명의 종류를 제공해서는 안됩니다. 이것이 REST의 하이퍼 미디어 제약이 피하고자하는 것입니다.

여전히 그렇게 설명 된 API를 개발할 수 있지만 결과 시스템은 REST 아키텍처 스타일을 구현하지 않으므로 REST에서 보장하는 속성 (특히 발전 가능성)이 없다는 점을 알고 있어야합니다.

예를 들어 인터페이스는 여전히 RPC보다 더 나은 솔루션 일 수 있습니다. 그러나 당신이 무엇을 만들고 있는지 알고 있어야합니다.

1 월

---

휴식 도구가 유용 할 수 있습니다 . RESTful API에 대한 사양, 모의 구현 및 자동화 된 단위 테스트를 작성하기 위해 언어에 구애받지 않는 접근 방식을 따릅니다.

API를 문서화하는 데만 사용할 수 있지만이 사양은 실제 서비스의 구현을 보장하는 데 즉시 사용할 수 있습니다.

서비스가 아직 완전히 구현되지 않았지만 예를 들어 웹 프런트 엔드 애플리케이션에서 사용해야하는 경우 rest-tool 은 서비스 설명에 따라 즉각적인 조롱을 제공합니다. 콘텐츠 스키마 유효성 검사 (JSON 스키마)는 문서 옆에 쉽게 추가 할 수있을뿐만 아니라 단위 테스트에서도 사용할 수 있습니다.

---

나는 나쁜 소식을 전하는 것이 싫지만, 당신이 나열한 것들을 문서화 할 필요가 있다고 느낀다면 아마도 REST 인터페이스를 만들지 않았을 것입니다.

REST 인터페이스는 단일 루트 URL을 식별 한 다음 해당 URL에서 반환되는 표현의 미디어 유형과 해당 표현의 링크를 통해 액세스 할 수있는 모든 미디어 유형을 설명하여 문서화됩니다.

어떤 미디어 유형을 사용하고 있습니까?

또한 문서 에 RFC2616 에 대한 링크를 넣으 십시오. 이는 모든 소비자에게 서비스와 상호 작용하는 방법을 설명해야합니다.

참고 URL : https://stackoverflow.com/questions/1714029/how-to-automate-documentation-of-a-rest-api-jersey-implementation