더블리의 12층

swagger에 대한 설치 및 이슈에 대해서 정리를 했었는데, 생각보다 쉽지 않은것 같다. swagger의 서버를 별도로 띄워서 사용하는게 이상한것 같고.. (별도의 서버가 있는데) 역시 공홈에 있는 문서를 읽는게 좋은것 같아서 이제는 공홈으로 왔다.

https://swagger.io/

swagger의 공홈을와서 Tools를 보면 총 3가지를 제공한다

• Swagger Codegen
• Swagger Editor
• Swagger Ui

swagger를 하나 떡! 설치하면 모든게 해결되는게 아니라는 사실을 여기서 느꼈다. 각각의 tool에 대해서 알아볼 필요가 있다고 생각한다. postman과 같이 APIs를 정리해놓을수 있지만, APIs의 서버를 만드는이상 APIs의 문서화는 필수라고 생각 (배보다 배꼽이 더 커보이지만 일단은 시작을 해보는게 좋을것 같아서! 아니면 지금 알아놓고 아니다 싶으면 다음에 하면 되니까!)

Swagger Codegen

• server stubs client SDKs를 생성할수 있게 해준다.
• 한마디로 OpenAPI(swagger에서 정의한)를 생성해놓고 개발팀은 그에 맞는 포맷으로 개발에 포커싱이 가능하다.
• 여기서 Available Clients, Avaliable Servers에 대해 나와있는데 각각의 프로젝트에서는 Codegen이 가능하다는 말!
• 약간 google protobuf와 같은 느낌같다 지금까지는... proto같이 파일을 정의하고 읽고, 쓰는 코드를 생성해주는?
• 일단 nodejs-server와 javascript가 가능하니 (현재 nodejs와 react를 사용할 예정이니)
• cloud에서도 제공을 하는데, SwaggerHub의 경우 14일만 사용이 가능하고 그 이후에는 유료버전으로 변경된다. (unlock이 그 의미가 맞겠지요)

• 처음 시작하면 Create a New API, Import an API가 있다.
• 들어가보면 특정 사용자들이 데모로 생성한 APIs도 확인이 가능하다. (그냥 데모 테스트할때 사용하면 좋을듯?)

• 정말 신세계구나... 이렇게 API를 만들어서.
• Template에는 Oauth 2.0, Simple 등등이 있음
• 참고로 public이 아니고 private으로 하면 계정을 upgrade 해야한다 (돈을 내라는거지)

• 이렇게 API가 어떤게 있고, Editor가 있다... 참 신기하다 이런게 있단.

• 이렇게 생성되고 나면 오른쪽 위에 Export가 있는데 여기서 이제 Client SDK, Server Stub을 자동으로 생성해준다.!!! Postman에서도 API를 호출하는 코드 생성도 너무 편리하게 사용했는데 여기서는 Server Stub까지 생성해주는구나..
• 참고로 Document를 다운받으면 html의 파일로 APIs 문서를 생성해준다.
• 실제로 Client SDK를 다운받으려 하는데 javascript는 없는데?
• 찾아보니 swagger-codegen generate의 CLI로 javascript코드 생성이 가능하다.

swagger-codegen generate \
  --input-spec http://petstore.swagger.io/v2/swagger.json \
  --lang javascript \
  --output . \
  --template-dir ./modules/swagger-codegen/src/main/resources/Javascript/es6 \
  --additional-properties usePromises=true,useES6=true

• OpenAPITools-github도 함께 살펴보면 좋을것 같다.

swagger-codegen-github

• 훌륭하게도 swagger-codegen은 opensource이다. 설치해서 사용하면 위에 호스팅을 자신의 서버에서 실행이 가능하다.
• 현재 버전 2.x와 3.x를 제공하는데 다른 브랜치에서 제공하니 원하는 버전을 사용하면 될것 같음
• 다른 패키지 설치 할필요없이 docker를 이용하자 code-gen-docker
• /gen/out아래 output이 생성

git clone https://github.com/swagger-api/swagger-codegen
cd swagger-codegen
./run-in-docker.sh mvn package


./run-in-docker.sh help # Executes 'help' command for swagger-codegen-cli
./run-in-docker.sh langs # Executes 'langs' command for swagger-codegen-cli
./run-in-docker.sh /gen/bin/go-petstore.sh  # Builds the Go client
./run-in-docker.sh generate -i modules/swagger-codegen/src/test/resources/2_0/petstore.yaml \
    -l go -o /gen/out/go-petstore -DpackageName=petstore # generates go client, outputs locally to ./out/go-petstore 

• 참고로 이렇게 설치하면 cli 툴만 설치했음, Hub에서 있었던 Editor는 따로 설치해야 한다.