Spec-insert plugin overview
출처: 문서
본문
Spec-insert 플러그인 개요
이 플러그인은 OpenAPI 스펙 컴포넌트를 Markdown 파일에 삽입하는 작업을 도와줘요. API 경로, path parameter, query parameter 같은 다양한 컴포넌트를 삽입할 때 사용할 수 있는 스니펫 세트를 제공해요. 이 문서에서는 플러그인 코드베이스에 대한 개요를 다뤄요. 코드베이스는 다음 섹션으로 나뉘어요:
- API parser: OpenAPI 스펙을 파싱하고 관련 컴포넌트 정보를 추출해요
- Component renderer: 추출한 컴포넌트 정보를 Markdown 형식으로 렌더링해요
- Reports: 이 플러그인용 리포트를 생성해요
API parser
다음 섹션에서는 API parser의 컴포넌트에 대한 정보를 살펴봐요.
SpecHash
SpecHash 클래스는 OpenAPI 스펙을 가져와서 $ref 필드를 역참조하는 역할을 담당해요. .load_file 메서드는 OpenAPI 스펙 파일의 경로를 받아서 스펙에서 발견한 모든 API action을 설정해요. config 파일의 text_replacements 기능도 여기서 관리해요.
API::Operation
API::Operation 클래스는 OpenAPI operation을 나타내요. 같은 그룹에 속한 operation들이 모여 하나의 API를 이뤄요.
API::Action
API::Action 클래스는 API action을 나타내며, URL 경로, query parameter, path parameter, request body, response body로 구성돼요. 이 컴포넌트들은 다음 클래스로 표현돼요:
Component renderer
컴포넌트는 mustache 템플릿을 사용해 Markdown으로 렌더링돼요. 각 spec-insert 컴포넌트는 renderer 클래스로 표현돼요:
BodyParameter: request body와 response body 테이블을 렌더링해요PathParameter: path parameter 테이블을 렌더링해요QueryParameter: query parameter 테이블을 렌더링해요Endpoint: endpoint 목록을 렌더링해요
이 컴포넌트들은 각각 SpecInsert 클래스 안에서 렌더링되는데, 이 클래스는 렌더링된 컴포넌트를 <!-- spec_insert_start -->와 <!-- spec_insert_end --> 주석으로 감싸요.
Reports
reports 폴더에는 사용 현황 리포트와 dry-run 리포트를 생성하는 코드가 들어 있어요. 이 리포트들은 Rakefile을 통해 실행할 수 있어요.