코드 주석을 통해 API 문서 생성

Question

내 API 문서를 생성하기 위해 aglio를 사용하고 있습니다. 저는 현재 API Blueprint 스펙을 기반으로이 부분에 대한 기본적인 마크 다운을 작성 중입니다. 코드에서 직접 주석을 통해 마크 다운을 생성 할 수있는 방법이 있는지 궁금합니다. 누구든지이 일을하는 방법을 알고 있습니까?

Answer 1

기술적으로

자세한 내용은 가능하다. 언어 및 사용 된 프레임 워크에 따라 다릅니다. 예를 들어 Ruby에서는 RSpec to generate API Blueprint을 사용할 수 있습니다.

Node.js와 비슷한 기능을하는 도구에 익숙하지 않습니다 (예 : Express.js DSL 사용).

청사진을 생성하는 도구를 작성할 때 수동으로 청사진 작성을 피하고 대신 Matter Compiler을 사용할 수 있습니다. 이 도구 (Ruby gem)는 JSON 또는 메모리 트리 (AST)를 API Blueprint로 변환합니다.

나는 코드에서 문서를 생성하는 것에 대해 개인적으로 조언합니다. 대신 API 청사진을 test your API implementation에 사용할 수있는 계약으로 간주합니다.

이 의미에서 코드에서 청사진을 생성하는 것은 코드에서 테스트를 생성하는 것과 같습니다 (동일한 코드를 테스트하는 것과 같습니다).

Answer 2

나는 agilo를 모르지만 다른 대안은 maven site plugin을 사용하여 API 문서를 생성하는 것이다.

<plugin> 
    <artifactId>maven-site-plugin</artifactId> 
    <groupId>org.apache.maven.plugins</groupId> 
    <version>${maven-site-plugin.version}</version> 
    <configuration> 
     <locales>en,fr</locales> 
    </configuration> 
    </plugin> 

API의 세부 정보가 포함 된 apt 파일을 작성하고 나중에 maven을 실행하여 문서를 생성 할 수 있습니다. 좋은 문서를 생성합니다. 어느 것이 광범위하게 사용되는 산업에서 매우 인기 있고 많은 사람들입니다. http://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html