store 폴더 안의 .js 파일에는 대개 일반적으로 위 다이어그램 녹색 점선안의 state, mutations, actions 를 정의해 놓는다. 컴포넌트가 렌더링 될때는, Vuex 의 state 에 접근할 수 있기 때문에 그 컴포넌트가 동작할때 필요한 값을 읽을 수 있고, 렌더링이 된 이후에는 상태값을 변경하기 위한 action 을 dispatch 하여 값을 mutate 할 수 있다.
Cron scheduler 와 queue 를 사용하는 로직을 로컬에서 구현하기 위해서는 local 피씨에도 해당 인프라를 만들어 놓는 것이 필요한데, Laradock 의 기본 설정은 내가 원하는 설정 부분이 빠져있거나, 사소한 오류로 인하여, Out of box 동작이 되지 않았기 때문에, 이를 위한 로컬 셋팅 작업을 한 뒤, 이 글을 빌어 그 기록을 남겨둔다.
workspace/crontab/laradock 에 내용을 아래 샘플과 같이 수정한 뒤 컨테이너 빌드를 다시하면 동작했다.
* * * * * laradock php /var/www/backend/artisan schedule:run >> /dev/null 2>&1
컨테이너 리빌드는 아래 명령을 사용하면 된다.
docker-compose up -d --force-recreate --build workspace
composer require laravel/horizon
php artisan horizon:install
php artisan queue:failed-table
php artisan migrate
config/horizon.php
config/database.php
config/queue.php
.env
#
#--------------------------------------------------------------------------
# Image Setup
#--------------------------------------------------------------------------
#
ARG PHP_VERSION=${PHP_VERSION}
FROM php:${PHP_VERSION}-alpine
LABEL maintainer="Mahmoud Zalt <[email protected]>"
RUN apk --update add wget \
curl \
git \
build-base \
libmemcached-dev \
libmcrypt-dev \
libxml2-dev \
zlib-dev \
autoconf \
cyrus-sasl-dev \
libgsasl-dev \
supervisor
RUN docker-php-ext-install mysqli mbstring pdo pdo_mysql tokenizer xml pcntl
RUN pecl channel-update pecl.php.net && pecl install memcached mcrypt-1.0.1 && docker-php-ext-enable memcached
# Install PostgreSQL drivers:
ARG INSTALL_PGSQL=false
RUN if [ ${INSTALL_PGSQL} = true ]; then \
apk --update add postgresql-dev \
&& docker-php-ext-install pdo_pgsql \
;fi
# Install Redis
ARG INSTALL_PHPREDIS=false
RUN if [ ${INSTALL_PHPREDIS} = true ]; then \
# Install Php Redis Extension
printf "\n" | pecl install -o -f redis \
&& rm -rf /tmp/pear \
&& docker-php-ext-enable redis \
;fi
RUN rm /var/cache/apk/* \
&& mkdir -p /var/www
#
#--------------------------------------------------------------------------
# Optional Supervisord Configuration
#--------------------------------------------------------------------------
#
# Modify the ./supervisor.conf file to match your App's requirements.
# Make sure you rebuild your container with every change.
#
COPY supervisord.conf /etc/supervisord.conf
ENTRYPOINT ["/usr/bin/supervisord", "-n", "-c", "/etc/supervisord.conf"]
#
#--------------------------------------------------------------------------
# Optional Software's Installation
#--------------------------------------------------------------------------
#
# If you need to modify this image, feel free to do it right here.
#
# -- Your awesome modifications go here -- #
#
#--------------------------------------------------------------------------
# Check PHP version
#--------------------------------------------------------------------------
#
RUN php -v | head -n 1 | grep -q "PHP ${PHP_VERSION}."
#
#--------------------------------------------------------------------------
# Final Touch
#--------------------------------------------------------------------------
#
WORKDIR /etc/supervisor/conf.d
[supervisord]
nodaemon=true
[supervisorctl]
[inet_http_server]
port = 127.0.0.1:9001
[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface
[include]
files = /etc/supervisor/conf.d/*.conf
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/backend/artisan queue:work redis --sleep=3 --tries=3
autostart=true
autorestart=true
numprocs=4
redirect_stderr=true
[program:horizon]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/backend/artisan horizon
autostart=true
autorestart=true
;user=laradock
numprocs=1
redirect_stderr=true
;stdout_logfile=/etc/supervisor/conf.d/horizon.log
### PHP Worker ############################################
php-worker:
build:
context: ./php-worker
args:
- PHP_VERSION=${PHP_VERSION}
- INSTALL_PHPREDIS=${PHP_WORKER_INSTALL_PHPREDIS}
- INSTALL_PGSQL=${PHP_WORKER_INSTALL_PGSQL}
volumes:
- ${APP_CODE_PATH_HOST}:${APP_CODE_PATH_CONTAINER}
- ./php-worker/supervisord.d:/etc/supervisor/conf.d
depends_on:
- workspace
extra_hosts:
- "dockerhost:${DOCKER_HOST_IP}"
- "demo.test:${HOST_IP_ADDRESS}"
- "backend.test:${HOST_IP_ADDRESS}"
networks:
- backend
docker-compose up -d --force-recreate --build php-worker
리빌딩이 끝나면 정상적으로 동작 하겠지만, 혹시나 supervisor 설정을 변경했을 경우, 아래의 명령으로 커맨드라인 접속 후
docker-compose exec php-worker ash
supervisor 의 새로운 설정내용을 반영하도록 한다.
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-worker:*
backend.test/horizon 에 접속하면, 위의 dashboard 가 출력되는 것을 확인할 수 있다. Yay!
Laravel Queues & Horizon Dashboard
ssh [email protected]
curl -sL https://github.com/thedevdojo/larasail/archive/master.tar.gz | tar xz && source larasail-master/install설치가 끝나면 이제 다음 커맨드를 실행한다.
larasail setupLaraSail 을 이용하면 LEMP stack 을 한방에 (composer, php7.2, mysql, nginx) 설치할 수 있다. 몇분간의 설치가 진행된 다음 LaraSail 로고와 함께 종료 메시지가 보였다면,
post_larasail.sh 라는 파일을 아래의 내용으로 만들고 실행하자. (Don’t forget to give it a 755 permission.)
위 스크립트는 기본 사용자인 larasail 을 SSH 접속 가능하게 만들며, 다음 단계에서 코드 배포를 위해 사용할 deployer 를 추가하고, Timezone, Locale 설정 등과 같은 house keeping chores 를 수행한다. (It definitely saved me some time. So you can expect the same as well.)
curl -LO https://deployer.org/deployer.phar
mv deployer.phar /usr/local/bin/dep
chmod +x /usr/local/bin/dep
ssh-keygen -t rsa -b 4096 -f ~/.ssh/github_rsa
ssh-keygen -t rsa -b 4096 -f ~/.ssh/bitbucket_rsa
ssh-copy-id -i -f ~/.ssh/github_rsa.pub [email protected]
ssh [email protected] -i ~/.ssh/github_rsa
ssh -T [email protected]
sites-available 설정을 하고
sudo nano /etc/nginx/sites-available/example.com
sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/
sudo certbot --nginx -d example.com -d www.example.com
sudo certbot renew --dry-run
larasail mysqlpass
CREATE DATABASE science DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'my-user'@'localhost' IDENTIFIED BY 'my-password';
GRANT ALL ON science.* TO 'my-user'@'localhost';
FLUSH PRIVILEGES;
cd /Code/laravel-app
dep init -t Laravel
github 또는 bitbucket repo 주소
host('159.65.xxx.xxx')
->user('deployer')
->identityFile('~/.ssh/id_rsa')
->set('deploy_path', '/var/www/html/laravel');
// before('deploy:symlink', 'artisan:migrate');
dep deploy 명령만 치면 된다.
단, git deploy 할 폴더가 deployer 권한으로 변경해야만 한다.
sudo chown -R deployer:www-data /var/www/html
just for the record, I am using Laradock for the local development, which is not in the scope of this article.
composer create-project --prefer-dist laravel/laravel toy
.env from .env.example and edit it to reflect your local development environment.
then update composer.json to include;
"barryvdh/laravel-cors": "^0.11.2",
"laravel/socialite": "^3.0",
"spatie/laravel-query-builder": "^1.11",
"tymon/jwt-auth": "^1.0.0-rc.3"
php artisan key:generate
php artisan jwt:secret
php artisan make:auth
php artisan migrate
php artisan vendor:publish --provider="Barryvdh\Cors\ServiceProvider"
php artisan vendor:publish --provider="Spatie\QueryBuilder\QueryBuilderServiceProvider" --tag="config"
app/Http/Kernel.php to include;
protected $middleware = [
// ...
\Barryvdh\Cors\HandleCors::class,
];
tymon/jwt-auth package configuration for your API auth.
config/auth.php to change api guard
'defaults' => [
'guard' => 'api',
// ...
],
:
'guards' => [
// ...
'api' => [
'driver' => 'jwt',
'provider' => 'users',
],
],
/routes/api.php
Route::group(['middleware' => 'auth:api'], function () {
Route::post('logout', 'Auth\[email protected]');
Route::get('/user', function (Request $request) {
return $request->user();
});
});
Route::group(['middleware' => 'guest:api'], function () {
Route::post('login', 'Auth\[email protected]');
Route::post('register', 'Auth\[email protected]');
Route::post('password/email', 'Auth\[email protected]');
Route::post('password/reset', 'Auth\[email protected]');
});
User model to implement JWTSubject interface like so.
use Tymon\JWTAuth\Contracts\JWTSubject;
:
class User extends Authenticatable implements JWTSubject
:
/**
* @return int
*/
public function getJWTIdentifier()
{
return $this->getKey();
}
/**
* @return array
*/
public function getJWTCustomClaims()
{
return [];
}
}
app/Http/Controllers/HomeController.php
and app/Http/Controllers/Auth/VerificationController.php.
and finally, update RedirectIfAuthenticated.php as follows;
if (Auth::guard($guard)->check()) {
return response()->json(['error' => 'Already authenticated.'], 400);
}
Route::get('{any}', function () {
return view('index');
})->where('any', '(.*)');
npm install -g @vue/cli
cool kids on the block 이 작성한 코드를 이해하지도 못한다는 사실은, 다시금 VueJS 학습에 대한 강한 동기를 마련해 주었다.
오늘은 어찌된 영문인지, Program with Erik 이란 유튜브 채널에서 VueJS 관련 방송을 하던 개발자가
5 Reasons Why You Shouldn’t Become A Software Engineer 라는 방송을 올렸던데, 비트코인 추락 속도마냥 엄청나게 빠른 속도로 1년전 기술이 도태되는 업종에서 일하는 공돌이 Ordeal 을 이야기한 내심은 잘 모르겠다. 어찌되었건, 넉넉하지 못한 시간을 쪼개서 항상 새로운 기술을 Radar 처럼 인지하고 있으면서 follow up 해야 하는 이 직업 상의 여유롭지 못함으로 인하여, 나 자신을 고지식하고 편협한 framework 속에 영원히 가두면서 살지 않았으면 좋겠다는 생각이 들었다.
index.blade.php 를 보니 HTML 의 scaffolding 을 라라벨 블레이드 엔진을 한번 통과하여 사용하고 있다. SPA 를 만들려고 했으면서, vue-cli 를 사용하지 않고, 굳이 이렇게 라라벨 디펜던시를 유지한건 좀 이상하지만, 문제의 핵심은 이것이 아니므로, 패스…
vue 를 제외하곤 로컬에 있는 디렉토리를 지정한 것이므로, ~/store 부터 한번 들어가 보겠다. 기본적으로 index.js 를 읽을거 같이 생겼으니, 오래 생각 안하고 해당 파일을 열어본다.
require.context() 는 webpack 을 이용해서, 기본으로 사용할 컴포넌트들을 global component 들로 레지스터를 하는 메서드라는 것 까지 알겠다. 그래도 드는 생각은 Duh… I still can’t get my head around the whole thing. 이때 문득, 이전에 버스 타고가다가 유투브로 본 7 Secret Patterns Vue Consultants Don’t Want You to Know – Chris Fritz 에서 들었던 내용이 떠올라 다시 보기로 한다. 요행히 어떤 사람이 이미 한글로 정리한 내용도 찾아진다. 하지만, 다시 보아도 직접적인 line by line 설명없이, 위의 코드를 이해하는데는 많은 도움이 되진 않았다. namespaced 옵션의 목적은 뭐고, require.context() 의 역할은 뭔지 등을 모르고서는, 파악이 되지 않아 또 다시 vuex 에 대한 구글링…
이번에 찾은 내용은 비디오 강좌였다. Vuex for Everyone 이라는 무료 비디오 강좌인데, 다행히… 원하는 내용을 커버하고 있었다. 근데, 이 사람 뭥미… 발음이 완전 인도사람 발음이라 뭔소리인지 잘 안들린다. 캡션이 제공되지 않았더라면… 흠… 나중에 찾아보니, Alex Kyriakidis 라는 그리스 사람이고, VueJS core 멤버란다. 가만 들어보니 인도 발음과 또 다르네 그려. 발음만 제외하면, 굉장히 핵심적인 내용을 명료하게 짚어주는 강의였기에, 게다가 무료. 추천 VueJS 컨텐츠 등극, 쾅… 어찌 어찌해서 보게된 이 비디오강의로 인하여, 시간상으론 상당한 detour 였으나, 그 강좌를 통해 vuex 사용법을 캐치업 하고 난 다음 다시 코드를 보니 store 코드들을 잘 이해할 수 있었다.
line #9 ~ #19 Vuex 에 필요한또한,state,getters,mutations,actions을namespaced module로 불러오겠다는 의미다.
mutations 부 에서는 state 변화만 처리하는 것이 best practice 이므로, store/modules/auth.js 와 store/modules/lang.js 의 mutations 부 에서 사용하는 있는 Cookie.set(), Cookie.remove() 는 actions 으로 이전시키는 리팩터링이 필요하겠다는 생각에 까지 도달했다.
router 관련 코드 인데, store 보다 많이 길고, 조금 더 난해하다.
SPA 의 라우팅을 담당하는 로직 부인데, 일단, 낯선 ‘vue-meta’, ‘vue-router’, ‘vuex-router-sync 내용을 포함하고 있으니, 해당 내용을 follow up 하기 위해 아래의 문서들을 먼저 읽었다.
vue-router 문서
vue-meta 문서
vue-router-sync 문서
라우터를 정의한 내용은 길기도 하거니와, 나 처럼 사전지식이 부족했던 사람들은 이해하기 쉽지 않을 것이므로, 상세히 line by line 설명을 적어보겠다.
line #11 ~ 12 글로벌 미들웨어, Vue Router 용어로는 Navigation Guards, 로 사용할 함수 컴포넌트 이름들 중 일부분이다.라라벨 백그라운드를 갖고 있기에 라라벨에서 사용하는 미들웨어 용어를 사용한 듯 싶다. 어쨌든, 귀여운 시도다. 여기에서는 네이게이션 가드 함수들 중에서, app 내의 모든 페이지 전환시 공히 사용하는
글로벌 미들웨어 의 키값을 우선 정의해 놓았다. 로케일과 인증 이므로, 납득이 가는 설정이다.
line #15 ~ 17
middleware 폴더에 존재하는 모든 .js 를 읽어서, export default 함수들을 import 한다.
코드 마지막 부분 (line #191 ~ 199) 에 있는 resolveMiddleware() 를 사용해서, 마치 store/index.js 의 하위 modules 폴더 안에 존재하는 모든 component 모듈들을 Webpack 의 require.context() API 를 사용하여 import 한 것처럼, 여기서는 router/index.js 의 하위 middleware 폴더 안에 존재하는 모든 export default 함수 모듈들을 import 한다.
line #19 ~ 23 이 앱에서 사용할 라우터 object를 생성한 다음, vuex 의라우터 object 를 생성하기 위해서, 라인 #30 ~ #41 에 정의된 createRouter() 함수를 사용하는데, 이때 이 함수는, 또 다시 Scroll Behavior 를 정의하기 위한store.state.route와 현재$route의 값을 sync 시키는 vue-router-sync 플러그인을 사용하기 위해, 해당 플러그인의 sync() API 를 호출한 다음, 생성된 라우터 object 를 default export 시켰다.
scrollBehavior() 함수와, Global Before Guards 를 등록하기 위한 beforeEach 함수와, Global After Hooks 를 등록하기 위한 afterEach 함수 등 모두 3개의 함수를 내부에서 사용한다.
line #169 ~ 185 Scroll Behavior 함수Vue Router 문서의 Scroll Behavior 부분을 읽어보면 이해가 어렵지 않다. savedPosition 이 있으면, 그 위치를 리턴하고, 이동할 to
route object 들의 anchor 포지션이 설정되었으면 그 selector 이름을 리턴하고, to route object 의 컴포넌트를 Vue Router 의 router.getMatchedComponents API 을 호출하여 알아낸다음 가장 마지막 component object 에 (ex. /pages/settins/profile.vue 컴포넌트 object 처럼) scrollToTop property 가 false 로 설정되어 있다면, 빈 {} object 를 리턴하여, 스크롤 위치를 보존하도록 하고, 이도 저도 아닌 fallback 로직으로는 { x:0, y:0 } object 를 리턴하여, 무조건 최상단으로 scroll 시키겠다는 내용이다.
참고로, router.getMatchedComponents({ ...to }) 는 component 인스턴스가 아닌 definition/constructor 가 배열로 리턴되며, console.log() 으로 찍어보면 아래와 같은 내용을 볼 수 있다. 나처럼 그 값들이 궁금했다면, 참고하시길…
[
{ middleware: "auth", _compiled: true, __file: "resources/js/pages/settings/index.vue", computed: {…}, beforeCreate:[…], … },
{ scrollToTop: false, _compiled: true, __file: "resources/js/pages/settings/profile.vue", computed: {…}, created: …, data: …, metaInfo: …, methods: …, … }
]
line #50 ~ 77 beforeEach 함수이 함수는 promise 를 리턴한다. (혹시, async + await 에 대한 내용이 익숙치 않다면, 이번 라라콘에서 CSS Grid 를 발표했었던
Wes Bos 의 관련 freeCodeCamp talk 유튜브 비디오을 봐도 되겠다. async + await 을 한줄로 설명한다면, promise 처리를 synchronously 이해할 수 있는 코드로 작성하는 방법이다.) 이젠 너무 반복된 코드의 설명은 빼고 나머지 코드의 내용을 설명하면, 61번~63번 라인은 컴포넌트 definition 에 명시적으로 loading property 가 false 라는 값으로 설정된 경우가 아니라면, App.vue 컴포넌트의 mounted() life cycle 에서, Vue.$loading 으로 지정한, (다시말해 router.app.$loading 로 접근가능한) Loading.vue 컴포넌트의 start() 메서드를 실행시킨다.
66번 라인은 match 되는 컴포넌트에서 모든 필요한 middleware 를 이전에 설정한 globalMiddleware 배열과 merge 한 결과를 구한다. 즉 컴포넌트에 middleware object 가 있는 경우, middleware 라는 이름의 배열로 리턴한다. middlewares 라고 썼음 더 좋으련만 내 코드가 아니니 또 패스.
69번~76번 라인은 각각의 미들웨어를 호출하는 부분이다. 참고로, Global Guard의 next() 함수 설명부를 보면 파이프라인의 다음번 hook 으로 이동하는 경우는 next() 함수 호출시 인자값이 없는 경우이다. 다시 말해 next() 의 인자가 undefined 인 경우만 next() 함수가 호출되어 다음 로직 이 진행된다. 이 점 유념하고, dynamic components 에 대한 이해를 높이기 위해 아래 VueJS 문서를 다시한번 정독했다. has anyone heard of RTFM?
flow 는 callMiddleware 함수로 넘어간다. 아래에 나열한 4개의 인자와 함께.
App.vue 컴포넌트의 layout 을 설정한다. 이 때, 첫번째 component 즉, components[0] 에 layout 가 설정되어 있는 경우는 그 페이지 layout 으로 설정하며, 아닌 경우에는 default layout 으로 설정한다. 다시 말해, routes.js 에서 지정하는 최상위 component 에 layout 옵션을 사용하면 원하는 layout 설정이 가능하단 말이다. default 레이아웃 (default.vue) 은 NavBar 가 포함되어 있고, basic 레이아웃 (basic.vue) 은 네비게이션 바가 없는 웰컴 페이지와 같은 데서 사용한다.
재귀호출의 시각은 124 번 라인의 _next() 로 시작하는데, 이를 위해 미들웨어 배열의 아이템들을 역순으로 바꾸고 하나씩 pop() 하여, 원래 지정한 components 순서대로, 가드를 하나씩 하나씩 재귀 호출한다. VueJS 에서 어떤 Route 에 대한 multiple guards 를 natively 지원하지 않기때문에 이런 hacky 방법을 쓰는데, vue-router-multiguard 라는 npm 패키지를 사용하면, 좀 더 읽기 편한 코드를 만들 수 있을 듯 하다. 왜 이런식으로 빙빙 돌려서 재귀호출을 하는지는 vue-router 리포의 관련 쓰레드에서 좀 더 읽어 볼 수 있다. 간단히 설명하자면, 가드가 여러개 있을때는, 어떤 가드에서 next() 를 바로 호출해 버리면 안된다. 다른 가드들을 거치면서, next() hook 이 호출되면 안되는 상황이 올 수도 있기 때문이다. 그래서 모든 가드들을 패스한 후, next() 를 마지막에 한번만 호출해야 되는 것이다.
app.js 의 Vue object 정의 맨 마지막에 들어간 App.vue 컴포넌트를 살펴본다. 기본 템플릿으론 loading 컴포넌트를 사용하고 라우터 가드들을 빠져나오면서 설정한 layout 으로 해당 layout 컴포넌트를 동적 로딩을 한다. 또한 둘다 공히 <child/> 컴포넌트를 사용하고 있다. Child.vue 파일을 보면 알 수 있듯이, 이 컴포넌트는 vue-router 에서 각 path 마다 매치되는 컴포넌트들을 보여주는 <route-view/> 컴포넌트를 제공하는 기본 템플릿라고 보면된다. 이후, vue-router 가 브라우저의 url 에 맞는 컴포넌트를 불러서 Child 컴포넌트의 <route-view> 안에 렌더링 시킨다.
크롬브라우저의 Vue.js devtools 익스텐션을 설치후 보면 위와 같은 계층적인 DOM 구조가 보인다. Yay!
나머지 주요 패키지로는 vue-i18n 과 vform 이 있는데, 로컬라이제이션과 form 패키지는 각각의 패키지 문서를 참고하기 바라면서 이 글을 마친다. 개인적으로, 로컬라이제이션 패키지와 폼밸리데이션은 다른 github 프로젝트들도 많이 있어서, monterail/vuelidate 프로젝트 등을 살펴보는 것도 필요해 보인다.
다음에는 vue-cli 와 vuetify.js 를 사용한 SPA 개발에 대하여 좀더 살펴보기로 하겠다.
Happy Coding!
올해 초 라라벨 API 프로젝트 작업할 때, SDK 코드제너레이션 까지는 아니더라도, 적어도 문서화를 위하여 Swagger 사용을 고려했었다. 구글에서 laravel swagger 라는 키워드로 검색후 발견한 L5-Swagger 패키지를 받았었는데, 그 부실한 문서와 (물론, 그 패키지가 래핑하고 있는 swagger-php 패키지의 문서도 그리 좋은 편이 아니어서) 장황하고 지저분한 annotation block 를 보고난 다음, 더우기 annotation 에서, 배열을 위한 square bracket 사용이 불가하다는 내용을 보니, 라라벨과 Swagger 콤보의 조합은 별로 어울리지 않는다는 결론과 함께 충만했던 호기심이 단번에 사라지고 말았다.
결국, API 문서화를 위해서는 API Blueprint 나, Slate, apiDoc 등의 alternative 들을 사용하는 바가 낫겠다는 생각 이었는데… 세월은 흘러, 어느덧 2018 라라콘 비디오가 유튜브에 올라오는 시기가 되었으니… 두둥…
TJ Miller 가 이번 라라콘에서 API 에 대하여 발표한 이 20180726 Laracon 2018 TJ Miller 프리젠테이션 을 보면, 다양한 API 핸즈온 경험들을 커버하는데, 여기에, OpenAPI 와 JSON Schema 에 대한 설명과, 그가 행하는 practice 를 이야기하는 부분이 나온다. 위의 그림에서처럼 기정의한 JSON Schema 를 레퍼런스 할 수 있다는 것과, 각각의 스키마들을 /schemas 폴더에 정리한 설명을 들어보니, 어라, 저런식으로 라라벨 프로젝트에서 Swagger(OpenAPI)를 사용하면 되겠구나 하는 아이디어를 얻게 되었다. 뿐만아니라, Speccy 프로젝트를 설명하면서 언급했던 Phil Sturgeon의 블로그를 보면, OpenAPI 와 관련된 더 많은 내용들을 읽어 볼 수도 있었다. 이 포스팅에서는 그 후, 회사 API 프로젝트에 Swagger 를 사용한 경험을 정리해 보기로 한다.
잠깐, Swagger(OpenAPI) 가 뭔데?
아직 마차에 타지 못한 사람들을 위해 짧은 설명을 첨부하자면, OpenAPI 는 JSON Schema 에 기반한 일종의 extension 으로, API 문서화 자동 생성, API 에 대한 다양한 언어를 위한 SDK 코드 자동 생성, Postman API 컬랙션 자동 생성 등의 다양한 API 개발 헬퍼 기능과 API 문서 자동생성 툴을 제공하는 소프트웨어 이다. OpenAPI 스펙은 .json 포맷 이나 .yaml 포맷으로 작성할 수 있는데, PHP 프로젝트에서 주석문 부분에 Doctrine annotation 을 추가하여, 해당 프로젝트용 OpenAPI 스펙을 자동으로 만들어주는 툴이 바로, swagger-php 이다. (참고로, OpenAPI v3 스펙 이전에는 OpenAPI 가 Swagger 로 불리였지만, v3 부터는 OpenAPI 로 이름을 바꿔었으므로, 이 둘을 interchangable 하게 불러도 헷갈려 하지 마시길.) Swagger v2 스펙은 JSON Schema draft v4 를 기반으로 하고, OpenAPI v3 스펙은 JSON Schema draft v5 를 기반하여 정의되었는데, 사실 OpenAPI 와 JSON Schema 는 약간 다른 목적을 두고, 독자적 body 로부터 독자 진화중이라서 그 둘 간 상이한 차이점이 존재하므로, 서로 다른 버젼 및 스펙간의 상호 컨버팅을 할 수 있도록 도와주는 프로젝트가 위에서 언급된 Speccy 이다.
어쨌든, 그럼 JSON Schema 는 도대체 뭐지?
JSON Schema 는 JSON 을 위한 메타 데이터를 정의하기 위한 스펙으로 그 목적은 아래와 같이 정리할 수 있다.
클라이언트가 보내는 데이터 validation 을 살펴보면 JSON Schema 의 목적들 중 하나를 좀 더 잘 이해할 수 있으리라 본다. 아래는 user 를 정의하는 JSON Schema 파일의 예 이다.
{
"$id": "http://example.com/schemas/user.json",
"type": "object",
"definitions": {},
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"name": {
"title": "Name",
"type": "string",
"description": "Users full name supporting unicode but no emojis.",
"maxLength": 20
},
"email": {
"title": "Email",
"description": "Like a postal address but for computers.",
"type": "string",
"format": "email"
},
"date_of_birth": {
"title": "Date Of Birth",
"type": "string",
"description": "Date of uses birth in the one and only date standard: ISO 8601.",
"format": "date",
"example": "1990–12–28"
}
},
"required": [
"name"
]
}
{
"name": "Lucrezia Nethersole",
"email":"[email protected]",
"date_of_birth": "2007–01–23"
}
Link: <http://example.com/schemas/user.json#>; rel="describedby"
Postman collection 생성, SDK 코드 자동 생성 등에 포커스를 두는 목적을 갖고있다고 이해하면 된다. 여기까지의 설명으로, 그 배경과 차이점을 알았으리라 판단되므로, 이제부터는 회사 프로젝트에 OpenAPI 를 적용한 내용을 살펴보기로 하자. (참고로, 현재 라라벨 프로젝트는 v5.6 을 사용하고 있다.)
* security={
* {"bearerAuth":{}}
* },
.json 형태의 output 생성시, 아래와 같이 정상적으로 생성되는 것에 반해
"security": [
{
"bearerAuth": []
}
]
.yaml 형태로 output 생성시에는 아래처럼
security:
-
bearerAuth: { }
[] 이 { } 로 출력되는 오류를 피하기 위한 workaround 로 sed 명령을 사용하여, 아래와 같이 어리버리한 { } 를 모두 [] 로 변경해주는 편법을 사용해야 한다.
./vendor/bin/openapi ./app | sed -E "s/(\{[ ]+\})/\[\]/" > openapi.yaml
/**
* @OA\Info(
* title="Search API",
* version="global-v2",
* x={
* "logo": {
* "url": "https://examples.com/logo.jpg",
* "altText": "Company Logo"
*
* }
* }
* )
* @OA\Server(
* url="http://search.test",
* description="local"
* )
* @OA\SecurityScheme(
* type="http",
* scheme="bearer",
* in="header",
* securityScheme="bearerAuth"
* )
*/
public function __invoke()
{
return response()->json([
:
]);
}
swagger-php 가 픽업할 수 있도록 한다. 결국 이 annotation 들이, 하나의 API end-point 에 대한 상응하는 OpenAPI 스펙으로 변환된다. 아래의 예에서 보는 것과 같이, 기정의 스키마들은 response 를 위한 3개의 .json 파일과, 1 개의 dto 를 위한 .json 파일을 지정하여, annotation hell 을 막을 수 있었고, 이런 식으로 적용하여, 보다 깔끔한 스펙작성과 배열 [] 이 {} 로 컨버팅되는 문제를 막을 수 있었다. (참고로, 이 예제에서 보이는 application 에서는 Elasticsearch 을 사용하여 검색을 수행하고, 그때 필요한 검색조건을 DTO object 로 전달하는 내용이 있기 때문에, 모델 정의 .json 을 지정하지 않고, 필요한 검색 DTO 정의 .json 스펙을 사용했다.)
/**
* @OA\Post(
* path="/api/v2/type",
* tags={"Match"},
* summary="맞춤소개",
* description="설명부분 어쩌구 저쩌구",
* security={
* {"bearerAuth": {}}
* },
* operationId="matchType",
* @OA\Response(response=200,
* ref="schemas/responses/match-type.json"
* ),
* @OA\Response(response="401",
* ref="schemas/responses/error-auth-invalid.json"
* ),
* @OA\Response(response="422",
* ref="schemas/responses/error-unprocessable-entity.json"
* ),
* @OA\RequestBody(
* required=true,
* @OA\MediaType(
* mediaType="application/json",
* @OA\Schema(
* @OA\Property(
* description="MatchDto",
* property="match_dto",
* ref="schemas/match-dto.json"
* ),
* @OA\Property(
* description="맞춤소개 타입",
* property="match_type",
* type="string",
* enum={
* "ugly",
* "good-looking"
* }
* ),
* type="object",
* )
* )
* )
* )
*/
public function match(MatchTypeRequest $request, Responder $responder)
{
:
}
schemas\responses\match-type.json 의 내용{
"description": "성공 응답",
"content": {
"application/json": {
"schema": {
"properties": {
"status": {
"type": "integer"
},
"success": {
"type": "boolean"
},
"data": {
"type": "object"
}
},
"type": "object",
"example": {
"status": 200,
"success": true,
"data": {
"list": {
"1100011": "CustomType",
"1200021": "CustomType",
},
"updated_at": "2018-10-01 09:00:00"
}
}
}
}
}
}
schemas\responses\error-auth-invalid.json 의 내용{
"description": "실패 응답 (인증실패)",
"content": {
"application/json": {
"schema": {
"properties": {
"status": {
"type": "integer"
},
"success": {
"type": "boolean"
},
"error": {
"type": "object"
}
},
"type": "object",
"example": {
"status": 401,
"success": false,
"error": {
"code": "auth_invalid",
"message": "Unauthorized request."
}
}
}
}
}
}
schemas\responses\error-unprocessable-entity.json 의 내용{
"description": "실패 응답 (처리불가)",
"content": {
"application/json": {
"schema": {
"properties": {
"status": {
"type": "integer"
},
"success": {
"type": "boolean"
},
"error": {
"type": "object"
}
},
"type": "object",
"example": {
"status": 422,
"success": false,
"error": {
"code": "unprocessable_entity",
"message": "insufficient search result"
}
}
}
}
}
}
schema\match-dto.json 의 내용 (상세 구현 내용은 중략){
"properties": {
"id": {
"description": "아이디",
"format": "int64",
"type": "integer"
},
"age": {
"description": "나이",
"format": "int32",
"type": "integer"
},
"timezone": {
"description": "타임존",
"type": "string",
"nullable": true
},
"gender": {
"description": "성별",
"type": "string"
},
"gender_preference": {
"description": "선호성별 리스트",
"type": "array",
"items": {
"type": "string"
}
},
:
"priorities": {
"description": "우선순위 리스트",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"age",
:
],
"type": "object",
"example": {
"id": 1155,
"age": 32,
"timezone": "Asia/Seoul",
"gender": "M",
"gender_preference": [ "F" ],
:
"priorities": []
}
}
ReDoc 은 yaml OpenAPI 스펙을 읽어서, 깔끔한 HTML 문서를 생성시켜주는 npm 프로젝트이며, 아래의 명령으로 redoc-cli 를 전역 설치한다.
npm i -g redoc-cli
.yaml 파일을 생성할때는, swagger-php 를 이용하여, Laravel 프로젝트 root 에서, /app 폴더 하위에 기록된 모든 annotation 들을 파싱해서 OpenAPI 스펙인 openapi.yaml 파일을 만들도록 ./vendor/bin/openapi --output openapi.yaml ./app 이라는 명령을 주면 되지만, 배열 [] 이 {} 로 출력되는 오류로 인해, 아래처럼 workaround 를 사용했다.
./vendor/bin/openapi ./app | sed -E "s/(\{[ ]+\})/\[\]/" > openapi.yaml
redoc-cli serve openapi.yaml --watch
Swagger-UI 프로젝트를 통해서도, 문서화된 내용을 만들어 볼 수 있는데, 여기서는 .json 로 생성한 스펙파일을 사용해보겠다. 우선 swagger-php cli 명령으로, 아래와 같이 openapi.json 스펙을 생성한다.
# json 파일 생성
./vendor/bin/openapi --output openapi.json ./app
docker 를 사용하여, swagger-ui 를 실행할 수 있는데, 다만, 아래의 ~/Code/search 의 경우, 현재 사용하는 PC 내의 로컬 폴더 path 이므로, 자신의 폴더 path 로 변경이 필요하겠다.
docker run -p 8081:8080 \
-e SWAGGER_JSON=/search/openapi.json \
-v ~/Code/search:/search \
-v ~/Code/search/schemas:/usr/share/nginx/html/schemas \
swaggerapi/swagger-ui
Postman 처럼 실제로 Curl 호출을 해볼 수 있는 인터페이스까지 포함된, 문서를 얻을 수 있다.
이번에, 사내 스터디에서 발표할 자료를 만들면서 정리한 블로그 포스팅은 여기까지 이며, 비슷한 고민을 하던, php 코더들에게 도움이 되었으면 하는 바램이다.
Happy Coding!