mares-swagger-spec-maker

mares framework 구조에 맞춰서openapi spec을 combine 해주는 모듈입니다.

Installation

npm install --save mares-swagger-spec-maker

Example

1const specMaker = require('mares-swagger-spec-maker')()
2
3// setting project root spec,
4let rootSpec = require('./.root-api-spec.js')
5
6// 각 서비스의 폴더를 추가해준다. 배열로 추가가 가능하다. 서비스별 폴더 구조는 아래에서 다시 설명한다.
7rootSpec = specMaker.merge(rootSpec, [require('./service-name')])
8
9// api prefix가 있다면 추가해준다.
10rootSpec.paths = specMaker.addPrefix(rootSpec.paths, this._prefix) //optional

root spec의 경우 .root-api-spec.js 라고 이름지어 줘야 하며, 형태는 다음과 같다. version, servers, info, components 정의가 가능하다.

1module.exports = {
2    openapi: "3.0.0",
3    servers: [{
4        url: env === 'development' ? 'http://localhost:8080' : 'https://aaaaa.com'
5    }],
6    info: {
7        description: packageJson.description,
8        version: packageJson.version,
9        title: packageJson.name,
10        termsOfService: 'http://swagger.io/terms/',
11        contact: {
12            email: 'aaa@aaaa.com'
13        },
14        license: {
15            name: 'Private',
16            url: 'http://aaaa.com'
17        }
18    },
19    components: {
20        schemas: {
21            Error: {
22                type: 'object',
23                required: ['rows', 'count'],
24                properties: {
25                    rows: {
26                        type: 'string',
27                    },
28                    count: {
29                        type: 'integer',
30                        description: '전체 에러의 수',
31                        example: 1,
32                        nullable: false
33                    }
34                }
35            }
36        }
37    }
38}

컨텍스트별 스펙의 경우 .context-api-spec.js 과 같이 파일명을 지어야 하며 형태는 아래와 같다. root components를 overriding 하고, tag를 지정하는데 사용된다.

1const meta = GET_META('infra-message');
2const spec = {
3    tags: [{
4        name: 'message',
5        description: '문자 발송, 발송된 문자 조회 등의 기능을 담은 API.'
6    }],
7    components: {
8        securitySchemes: {
9            ApiKeyAuth: {
10                type: 'apiKey',
11                in: 'header',
12                name: 'X-API-TOKEN'
13            }
14        },
15        schemas: {
16            PhoneNum: {
17                type: 'string',
18                pattern: /(^\+[0-9]{2}|^\+[0-9]{2}\(0\)|^\(\+[0-9]{2}\)\(0\)|^00[0-9]{2}|^0)([0-9]{9}$|[0-9\-\s]{10}$)/,
19                minLength: meta.std.message.minPhoneNumLength,
20                maxLength: meta.std.message.maxPhoneNumLength,
21                description: '문자를 받을 수 있는 전화번호, +국가코드 형태가 되어야 한다.',
22                example: '+821011112222',
23                nullable: false
24            }
25        },
26        parameters: {
27            messageContextLimitParam: {
28                in: 'query',
29                name: 'limit',
30                description: '최대 불러올 데이터 row 수',
31                required: false,
32                schema: {
33                    type: 'integer'
34                },
35                example: meta.std.default.defaultContentsLength
36            }
37        }
38    }
39}
40module.exports = spec

다음으로 버전에 대한 스펙이 있다. .version-api-spec.js 라고 이름 지어줘야 한다.

1module.exports = {
2    in: 'path',
3    name: 'version',
4    description: '버전 값',
5    required: false,
6    schema: {
7        type: 'string',
8        enum: ['v1'],
9        default: 'v1',
10        example: 'v1'
11    }
12}

마지막으로 실제 router spec을 정의해야한다. .spec.js 로 정의한다. 전체 스펙에서 url 부분부터 정의를 해주면 된다.

1const meta = GET_META('message-context');
2
3const spec = {
4    '/{version}/messages': {
5        get: {
6            tags: ['message'],
7            summary: '문자 내역 확인',
8            operationId: 'findMessages',
9            description: '해당 스펙에서 message 라는 의미는 발송된 문자를 의미한다. 해당 API는 발송했던 문자 내역을 불러온다.',
10            parameters: [{
11                $ref: '#/components/parameters/messageContextOffsetParam'
12            }, {
13                $ref: '#/components/parameters/messageContextLimitParam'
14            }, {
15                in: 'query',
16                name: 'templateKey',
17                description: '문자 발송시 이용된 템플릿의 키 겁색 (prefix 검색 가능)',
18                required: false,
19                schema: {
20                    type: 'string',
21                    example: 'templateKey123',
22                    nullable: false
23                }
24            }],
25            responses: {
26                '200': {
27                    description: '불러오기 성공',
28                    content: {
29                        'application/json': {
30                            schema: {
31                                type: 'object',
32                                properties: {
33                                    rows: {
34                                        type: 'array',
35                                        items: {
36                                            $ref: '#/components/schemas/MessageDomain'
37                                        },
38                                        description: '문자 도메인 배열'
39                                    },
40                                    count: {
41                                        type: 'integer',
42                                        description: '해당 조건에 해당하는 전체 문자 도메인 카운트'
43                                    }
44                                }
45                            }
46                        }
47                    }
48                }
49            }
50        }
51    }
52}
53module.exports = spec

최종적으로는 아래와 같이 사용이 가능하다.

1
2const getSpec = () => {
3    // 최상단 루트 스펙을 가져온다.
4    let rootSpec = require(path.resolve(rootPath, '.root-api-spec.js'))
5    
6    // 루프를 돌면서 마레스 모듈을 읽어와서 루트스펙에 머지한다,.
7    for (let i = 0; i < contexts.length; ++i) {
8        let moduleName = path.basename(contexts[i])
9        rootSpec = specMaker.merge(rootSpec, path.resolve(rootPath, moduleName))
10    }
11    
12    // 모든 url에 prefix를 붙여준다. 예를들면 account/users 라는 리소스가 있다면 prefix/account/users라고 변경이 된다.
13    rootSpec.paths = specMaker.addPrefix(rootSpec.paths, prefix)
14    
15    // 모든 루트스펙에 선언된 컴포넌트 ($ref) 를 실제 객체로 바꿔준다. (이유는 실제 객체를 통해 router에서 parameter, requestBody 등을 validation하기 위함이다.)
16    rootSpec = specMaker.replaceAllComponents(rootSpec)
17    
18    // 필요한 곳에 리턴한다.
19    return rootSpec	
20} 

Structure

폴더 및 파일 구조는 다음과 같다.

1. 루트 프로젝트: .root-api-spec.js가 위치한다.
2. service 폴더: 서비스폴더 루트에 .context-api-spec.js 가 존재한다.
   1. presentation: 프레젠테이션 레이어
      1. v1: api 버전폴더: 해당폴더 안에 version-api-spec.js가 존재한다.
         1. resourceName: 해당폴더 안에 .spec.js가 존재한다.
   2. application: 어플리케이션 레이어
   3. domain: 도메인 레이어
   4. infra: 인프라스트럭쳐 레이어
   5. test: test 코드