더블리의 12층

• Router 모듈 나누는 방법
  • api, main, ...
• service-controller-route 구조 이해
• express-js-best-controller-pattern

• elasticsearch-and-nodejs-tutorial
• how-to-build-a-real-time-search-engine-with-node-vue-and-elasticsearch

오늘 하루종일 swagger를 찾아보다가 드는 의문이, swagger.yaml을 생성하고 그 파일을 바탕으로 nodejs, spring, go framework에 맞는 코드를 생성하면 뭐하지? 내가 그 안을 채웠을때 swagger.yaml과 어떻게 sync를 맞출까... 매번 swagger.yaml을 기준으로 수정하고 다시 코드를 생성하는걸까...? 뭐가 맞는지 정말 모르겠다. Springboot의 경우 annotation을 작성해서 자동으로 swagger.yaml을 만드는데 코드 -> swagger.yaml을 생성이 맞는게 아닐까? swagger.yaml의 역할이 blueprint의 역할을 한다면 swager.yaml에서 코드를 만드는게 맞는것 같기도하고..

뭐가 맞는지는 모르겠지만 일단 koa-swagger-decorator를 찾았다. decorator는 코드에 decorator를 작성해서 swagger json docs을 자동으로 생성해주는 역할을 한다. 내코드가 swagger json을 생성해주니까, 코드만 수정하면 swagger-ui에 바로 반영이 된다.

$ npm install koa-swagger-decorator

현재 swagger에서는 OpenAPI 3.0까지 지원하던데 해당 코드는 Swagger OpenAPI 2.0을 기준으로 한다. migration이 가능할것 같으니 일단은 그냥 사용해보는걸로.. 위 패키지를 설치하고 다음과 같이 코드를 추가한다.

import { SwaggerRouter } from 'koa-swagger-decorator'

사용성이 구려서 사용안하기로

• 10-best-practices-for-writing-node-js-rest-apis
• checklist-best-practice-of-node-js-in-production
• nodejs-express-server-github
  • nodejs-express로 작성된 서버 OpenAPITools로 생성된

authenticate-a-node-es6-ap-with-json-web-tokens

• swagger-apis-github

설치

$ npm install -g swagger or sudo npm install swagger
$ swagger project create swagger
$ swagger project edit

$ swagger project create swagger

• Framework?라고 물어보는데 swagger-node를 살펴보면 swagger CLI에 대해서 설명이 되어 있다.
• 각각의 framework에 대한 비교

? Framework? 
  connect 
  express 
  hapi 
  restify 
❯ sails 

• express를 선택

$ swagger project edit

• API 문서 수정

Swagger Server 에 비즈니스 로직 추가하기

function hello(req, res) {
    var name = req.swagger.params.name.value || 'stranger';
    var hello = util.format('Hello, %s!', name);
    res.json({ "message": hello });
}

Swagger Edit에서 수정

x-swagger-router-controller에 아래와 같이 추가

    paths:
        /hello:
            x-swagger-router-controller: hello_world

이슈

설치시 이슈

• sudo를 사용했음에도 아래와 같이 에러가 발생
• swagger-install 을 살펴보면 npm에서 -g옵션을 사용은 설정에 따라서 사용
• $ sudo npm install swagger 해도 실패
• xcode install & node-gyp 을 하니 정상적으로 설치가 완료

gyp ERR! stack Error: EACCES: permission denied, mkdir '/Users/direcision/.nvm/versions/node/v12.15.0/lib/node_modules/swagger/node_modules/fsevents/.node-gyp'

Swagger 시작시에 오류

• swagger project start를 했을때 아래와 같이 에러가 발생했다.
• github-issue를 확인해보니 nodev12에서 생기는 에러여서 node10으로 downgrade를 하던지
• (실패) 첫번째 방법 npm install --save swagger-router을 하라고 하는구나. 이렇게 하니까 정상적으로 실행이 되는데 음...~ 이 방법으로 하면http://127.0.0.1:10010/hello?name=Scott`으로 했을때 에러가 난다. 정상적으로 수정하는 방법이 아님. 아래 방법이 좋을듯
• (실패) 2번째 방법 또는 nodev12에서 실행하는방법
  • swagger-express-mw의 버전이 기존에는 ^0.1.0인데 ^0.7.0으로 업데이트를 하고
    • $ npm install swagger-express-mw@0.7.0
    • swagger_params_parser를 swagger_controllers로 추가 (config/default.yaml에`
    • 동일하게 curl http://127.0.0.1:10010/hello?name=Scott을 실행하면 Cannot read property 에러가 발생
• (성공) 세번째 방법으로 node_modules/bagpipes/lib/fittingTypes/user.js file을 아래와 같이 변경
  • var split = err.message.split(path.sep);
  • var split = err.message.split('\n')[0].split(path.sep);

Error: Cannot find module '/Users/direcision/Desktop/ToyProjects/web/server/swagger/api/fittings/swagger_router'
Require stack:
- /Users/direcision/Desktop/ToyProjects/web/server/swagger/node_modules/bagpipes/lib/fittingTypes/user.js
- /Users/direcision/Desktop/ToyProjects/web/server/swagger/node_modules/bagpipes/lib/bagpipes.js
- /Users/direcision/Desktop/ToyProjects/web/server/swagger/node_modules/bagpipes/lib/index.js
- /Users/direcision/Desktop/ToyProjects/web/server/swagger/node_modules/swagger-node-runner/index.js
- /Users/direcision/Desktop/ToyProjects/web/server/swagger/node_modules/swagger-express-mw/lib/index.js
- /Users/direcision/Desktop/ToyProjects/web/server/swagger/app.js
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:793:17)
    at Function.Module._load (internal/modules/cjs/loader.js:686:27)
    at Module.require (internal/modules/cjs/loader.js:848:19)
    at require (internal/modules/cjs/helpers.js:74:18)
    at createFitting (/Users/direcision/Desktop/ToyProjects/web/server/swagger/node_modules/bagpipes/lib/fittingTypes/user.js:18:20)
    at Bagpipes.newFitting (/Users/direcision/Desktop/ToyProjects/web/server/swagger/node_modules/bagpipes/lib/bagpipes.js:158:17)
    at Bagpipes.createFitting (/Users/direcision/Desktop/ToyProjects/web/server/swagger/node_modules/bagpipes/lib/bagpipes.js:147:22)
    at Bagpipes.createPipe (/Users/direcision/Desktop/ToyProjects/web/server/swagger/node_modules/bagpipes/lib/bagpipes.js:111:19)
    at Bagpipes.getPipe (/Users/direcision/Desktop/ToyProjects/web/server/swagger/node_modules/bagpipes/lib/bagpipes.js:50:38)
    at /Users/direcision/Desktop/ToyProjects/web/server/swagger/node_modules/bagpipes/lib/bagpipes.js:34:10

npm install -g <packagename>을 했을때 실패를 해서 로그를 보니 아래와 같이 로그 에러가 나고 있었다.

gyp: No Xcode or CLT version detected!
gyp ERR! configure error
gyp ERR! stack Error: `gyp` failed with exit code: 1
gyp ERR! stack     at ChildProcess.onCpExit (/Users/direcision/.nvm/versions/node/v12.15.0/lib/node_modules/npm/node_modules/node-gyp/lib/configure.js:351:16)
gyp ERR! stack     at ChildProcess.emit (events.js:223:5)
gyp ERR! stack     at Process.ChildProcess._handle.onexit (internal/child_process.js:272:12)
gyp ERR! System Darwin 19.3.0
gyp ERR! command "/Users/direcision/.nvm/versions/node/v12.15.0/bin/node" "/Users/direcision/.nvm/versions/node/v12.15.0/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
gyp ERR! cwd /Users/direcision/.nvm/versions/node/v12.15.0/lib/node_modules/swagger/node_modules/fsevents
gyp ERR! node -v v12.15.0
gyp ERR! node-gyp -v v5.1.0
gyp ERR! not ok
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@1.2.11 (node_modules/swagger/node_modules/fsevents):
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@1.2.11 install: `node-gyp rebuild`
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: Exit status 1

github-issue를 살펴보니 아래와 같이 설치하고 추가하니 정상적으로 설치가 된다.

following step help me to resolve this issue on Mac Catalina OS

$ sudo rm -rf $(xcode-select -print-path)
$ xcode-select --install
$ /usr/sbin/pkgutil --packages | grep CL
$ sudo npm install -g node-gyp

npm install -g <packagename>에서 가장 찝찝한건 global에 설치한다는게 너무 찝찝했다. 또 이렇게 global로 설치할때는 sudo의 권한이 필요했으니... sudo는 뭔가 찝찝 찾아보다가 npm install을 한 패키지의 내용을 계정의 root로 설치해 sudo없이 설치가 가능하다는 것이다.

$ npm set prefix ~/npm

# bash_profile
PATH=~/npm/bin:$PATH

이렇게 설정하면 npm 패키지 설치할때 sudo권한이 필요없다.

• 참고
  • using npm without sudo