docs

slate docs로 API 문서 만들기 (1) - 기본 페이지 만들기

pepega 2023. 3. 1. 16:10

slate는 markdown 수정만으로 API 문서를 만들 수 있는 오픈소스입니다.

 

https://awesomeopensource.com/projects/api-documentation

여기서 가장 별이 높은 오픈소스를 참고했습니다.

 

이 오픈소스에서는

 

위와 같은 배포 방식을 사용할 수 있게 되어있습니다.

 

이 블로그에서는

Github pages를 활용하여 만들 예정입니다.

 

만약 container 이미지를 만들어 배포하고 싶은 경우

https://medium.com/upday-devs/how-to-run-api-documentation-on-kubernetes-using-slate-and-nginx-2608ce7d6cea

위 문서를 참고하면 좋습니다.

 

 

기본 페이지 만들기

 

https://github.com/slatedocs/slate

slate github에 접속합니다.

 

 

Use this template -> Create a new repository를 클릭합니다.

 

필요한 정보를 입력하고

 

Create repository from template을 클릭합니다.

 

 

사진처럼 나만의 repository가 생겼습니다.

 

repository가 생성되면 github action에서

build와 deploy를 진행하며

gh-pages 라는 branch가 생성됩니다.

 

완료 될 때까지 기다립니다.

 

빌드가 완료됨과 동시에 gh-pages라는 branch가 생성되었습니다.

 

해당 branch를 기준으로 github page를 생성하겠습니다.

 

repository -> Settings -> Pages을 클릭합니다.

 

Branch를 gh-pages로 변경하고 Save를 클릭합니다.

 

 

repository에 Environments가 생기면서

github-pages가 추가되었습니다.

 

https://ghghghko.github.io/slate/#introduction

 

위 주소에 접속하면

slate docs가 만들어진 것을 확인 할 수 있습니다.

 

다음 글에서는

index.html.md 파일 수정 후 push하여

 

slate docs의 내용이 변경되는지 확인하겠습니다.

 

 

참고자료

https://docs.github.com/ko/actions

https://github.com/slatedocs/slate

https://awesomeopensource.com/

https://medium.com/upday-devs/how-to-run-api-documentation-on-kubernetes-using-slate-and-nginx-2608ce7d6cea

 

'docs' 카테고리의 다른 글

slate docs로 API 문서 만들기 (2) - 내용 수정하기  (0) 2023.03.01