Stoplight Getting started tutorial 실습 후기

Stoplight 자료가 생각보다 찾기 힘들었다.

다행히 영문으로 된 튜토리얼을 찾아냄!! 👏👏

 

Documenting APIs(a guide for technical writers)라는 사이트인데-

튜토리얼이 정말 상세하다.

(이 정도로 디테일하다고?! 싶을 정도로 자세함)

Stoplight를 처음 써봄에도 튜토리얼에서 막히는 부분이 없었음!!

드디어 찾았다 내 롤모델 😆

 

https://idratherbewriting.com/learnapidoc/pubapis_openapis_quickstart_stoplight.html

Getting started tutorial: Using Stoplight Studio to create an OpenAPI specification document

 

튜토리얼을 직접 따라해보면서 느낀 후기를 공유하고자 한다.

 

Using a visual editor

Q. GUI를 왜 쓰는가?

OpenAPI specification을 작성할 떄 GUI 툴을 안쓰고 하나하나 코딩해서 한다고 가정하자

그럼 문서 퀄리티에 집중하지 못하고

Valid syntax인지 검수하는 등

공수가 너무 많이 들어가게 됨

 

GUI를 이용하면

이런 불필요한 작업을 안해도 되고

진짜 딱 콘텐츠에 집중할 수 있음

왜냐? stoplight에서 필요한 기능은 다 UI에 이미 구현을 해놨으니까

(마치 API 자세히 몰라도 KAS Console에서 이미 구현된 UI 이용하면 되는 것과 같음)

 

Stoplight의 장점

GUI와 code를 번갈아가며 쓸 수 있다

seamlessly switch between Form and Code views
Form에서 뭔가 수정하면 code에 바로 반영됨

Description에 Hello!를 추가함

 

Code에 가니 자동으로 추가한 문구가 반영돼있음 (따로 손덴거 없음)

Preview로 어떻게 보는지 바로 볼 수 있음

회사 기술 문서 중 ref docs는 npm run을 해야지 미리보기를 할 수 있음 -> 바로 미리보기가 되진 않는다

Stoplight는 form - code - preview 사이에서 switch가 즉각적으로 되는게 큰 장점!

The ability to switch views between Form, Code, and Preview

게다가 Docs에서 한걸 Try It에서 바로 실행해볼 수도 있음

If not? 지금 회사에서 문서 편집은 Visual Studio Code에서 하고

API Request 실행은 Postman에서 함

즉, 이 문서 편집과 API 실행을 각각 다른 툴에서 따로 해야 하는데

Stoplight는 이 2개를 합쳐놓음

 

문서 버전과 API 버전을 따로 표기할 수 있음

문서 버전은 yaml 파일명에 표기하면 됨
e.g. openweathermap.v1.yaml

왼쪽은 문서 버전이 회색 바탕에 v1으로 있음 오른쪽은 문서 버전 표기 안돼있음

문서 버전명이 yaml에 추가되지 않은 default 상태

파일명에 .v1.을 추가해줌

이제 제대로 문서 버전 나타남

아쉬운 점

로컬 stoplight studio 애플리케이션에서 login 하는 법?

Postman은 desktop application에서 로그인하면 웹 버전에서도 연동이 돼서 편리하다.

(작업한 내용도 날라가지 않고 저장됨)

 

Stoplight는 따로 연동은 안되는 듯 흠...

이 점이 조금 아쉽다.

 

그치만 딱히 로컬 버전 안쓰고 웹 버전에서만 작업해도 상관없을듯

웹 버전만 쓰면서 특별히 불편한 건 없었다.

 

튜토리얼 실습해본 것

by 원작자

OpenWeatherMap API | OpenWeatherMap3

 

by Sunny

OpenWeatherMap API | OpenWeatherMap3_Sunny