OpenAPI 3.0 스펙 사용

https://swagger.io/specification/

참고 사이트

• https://editor.swagger.io/ : 편집, 가져오기, 내보내기, 변환, 작성오류 추적 등 용이함
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md : 작성 샘플

작성 도구 - WebStrom 플러그인

• OpenAPI (Swagger) Editor

예시

openapi: 3.0.3
info:
  title: Project API
  description: Project API DOC
  contact:
    email: 1024corp@1024corp.com
  version: 0.0.1
servers:
  - url: <https://dev-api.com>
    description: 테스트 서버
  - url: 
    description: 로컬 서버
tags:
  - name: 회원(Member) API
paths:
  "/api/v1/member/{id}":
    put:
      tags:
        - 회원(Member) API
      summary: 회원 수정
      description: 회원 수정 API
      operationId: V1MemberUpdate
      parameters:
        - name: id
          in: path
          required: true
          example: 1
          description: 회원 식별자 정보
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_name:
                  type: string
                  example: ModifyName
                  description: 수정 이름 정보
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                    example: 0.0.1
                    description: Version
                  timestamp:
                    type: number
                    example: 1672531200
                    description: Unix Timestamp
                  meta:
                    type: object
                    nullable: true
                    example: null
                    description: Meta
                  data:
                    type: object
                    nullable: true
                    example: null
                    description: Data
                required:
                  - version
                  - timestamp
                  - meta
                  - data
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: array
                    items:
                      type: object
                      properties:
                        statusCode:
                          type: number
                          example: 400
                        message:
                          type: string
                          example: user_name must be a string
                        error:
                          type: string
                          example: Bad Request
                required:
                  - message
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "409":
          description: Conflict
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: array
                    items:
                      type: string
                    example: [user_name cannot be modified.]
                required:
                  - message
      security:
        - AccessToken: []
components:
  schemas: {}
  securitySchemes:
    AccessToken:
      type: apiKey
      in: header
      name: access_token
      description: Enter your Access Token

1. 기본 정보
   • openapi : openAPI 버전 명시
   • info : api의 정보
2. 서버 정보
   • servers : 호스팅 서버 정보
3. 경로
   • paths : api 엔드포인트 경로, 각 경로에는 HTTP 메서드(GET, POST, PUT, DELETE 등)와 해당 경로의 요청/응답 형식을 정의하는 섹션을 포함한다
4. 주석
   • tags : api를 그룹화 하기 위한 태그 정의
   • summary, description : api에 대한 설명
5. 요청
   • parameters : 매개변수 정의
   • requestBody 요청 본문 형식 정의
6. 응답
   • response : 응답 형식 정의, 상태 코드와 응답 형식 지정, content 필드에 데이터 스키마 형식 지정
7. 보안 / 인증
   • security : api의 인증 방법 정의
   • securitySchemes : 사용되는 인증 체계 정의

Background

프로그래머의 가장 어려운 업무가 이름 짓기라는 설문 결과도 있듯이 변수에 적절한 이름을 지어주는 것은 어렵고 오래걸리는 일이다.

영어가 모국어가 아닌 사람들에게는 더 어려울 수 밖에 없는데 특히 Bool 변수명을 올바르게 지으려면 몇가지 영문법을 숙지해야한다. Bool 변수명은 사소한 차이로도 의미가 많이 바뀌어 코드를 읽는 사람을 더 헷갈리게 할 수도 있기 때문에 조금이라도 더 명확하고 문법적으로 맞는 Bool 변수명을 짓는 것이 중요하다는 생각이다.

Cases

Cocoa Touch의 여러 클래스들을 훑어보면서 Bool 변수 작명을 위해 알아야하는 영문법을 네 가지 케이스들로 정리해봤다.

• is 용법
• 조동사 용법
• has 용법
• 동사원형 용법

is 용법

is로 시작하는 변수명이 가장 흔한 케이스 아닌가 싶다. 뒤에 나오는 단어의 특징에 따라 세 가지로 나눌 수 있다.

• is + 명사
• is + 현재진행형(~ing)
• is + 형용사

is + 명사

“(무엇)인가?” 라는 뜻으로 쓰인다.

func isDescendant(of view: UIView) -> Bool //UIView: "view의 자식인가?" 

is + 현재진행형(~ing)

“~하는 중인가?” 라는 뜻이 필요할 때 쓰면 된다.

var isExecuting: Bool { get } //Operation: "오퍼레이션의 작업이 현재 실행 중인가?"
var isPending: Bool { get } //MSMessage: "메시지가 보내지기 전 대기 중인가?"

is + 형용사

이제부터 살짝 헷갈릴 수 있다.

형용사도 두 종류로 나뉜다.

• 단어 자체가 형용사인 것 - opaque, readable, visible 등
• 과거분사 형태 - hidden, selected, highlighted, completed 등

과거분사(past participle)는 간단히 말해 동사로 만든 형용사라고 생각하면 된다. 동사를 과거분사로 바꾸면 뜻이 여러가지로 바뀔 수 있는데, 일단 여기서는 수동태라고 생각하면 되겠다. hide(숨다) - hidden(숨겨진), select(선택하다) - selected(선택된), complete(완료하다) - completed(완료된) 등등. (보다시피 동사 뒤에 -ed가 붙는 형태가 가장 흔하지만, 내가 쓰려는 동사의 과거분사를 모르겠으면 사전을 찾아보자.)

UIKit을 쓰다보면 정말 많이 보는 UIView의 프로퍼티들이 이런 경우다.

var isOpaque: Bool { get set }
var isSelected: Bool { get set }
var isHighlighted: Bool { get set }
var isHidden: Bool { get set } 

❗주의❗is로 시작하는 변수명을 짓다가 범하는 흔한 실수가 바로 is + 동사원형 을 쓰는 것이다.

isAuthorize, isHide, isFind 등등.

가령,

var isEdit: Bool //gg

edit이라는 단어가 명사로 쓰일수도 있어서 해석의 여지는 있지만 뜻이 명확하지 않아 일반적으로는 곧바로 해석하기 쉽지 않다. 😧 더 잘 할 수 있다.

아래와 같이 적절하게 바꿔주면 해석이 더 쉽고 빠르다.

var isEditable: Bool //편집할 수 있는가?
var isEditing: Bool //편집 중인가?
var canEdit: Bool //편집할 수 있는가? -> 다음 '조동사 용법' 섹션 참고

4월 11일 추가

닷넷 프레임워크에 DataRowView.IsEdit이라는 불리언 변수가 있다는 제보를 받았다. 문서를 보면 ‘row가 edit mode인지’를 나타내는 불리언인데 닷넷 개발자가 아닌 다른 개발자가 edit mode 라는 것을 모르는 상태에서 문서를 읽어보지 않고는 한번에 이해할 수 없었을 것이다. 하지만 만약 IsEdit이 닷넷 프레임워크에서 자주 쓰이는 변수명이자, edit이 edit mode를 의미한다는 것이 컨벤션이라면 괜찮을 수 있다. 변수명에 신경쓰는 이유 자체가 다른 개발자(또는 내일의 나)가 내 코드를 쉽고 빠르게 이해하게 하려는 것이기에.

조동사 용법

조동사(modal verb)는 동사를 돕는 동사란 뜻인데 can, should, will 등이 있다. 주의할 점은 조동사 + 동사원형 으로 써야한다는 것 하나 뿐이다.

can: “~ 할 수 있는가?”

should, will: “~ 해야 하는가?” 혹은 “~ 할 것인가?”

등등.

var canBecomeFirstResponder: Bool { get } //UIResponder: first responder가 될 수 있는가?
var shouldRefreshRefetchedObjects: Bool { get set } //NSFetchRequest: 가져온 값을 refresh 할 것인가?

has 용법

has로 시작하는 Bool 변수명은 상대적으로 빈도가 낮지만 뜻이 전혀 다르게 쓰이는 두 가지가 있어서 알아두면 유용하다.

• has + 명사
• has + 과거분사

has + 명사

has 다음 명사가 나오면 “~를 가지고 있는가?” 라는 뜻이다. has는 have의 3인칭 단수인데 3인칭 단수에 대해서는 다음 파트에서 자세히 다룬다.

var hasiCloudAccount: Bool { get } //CKUserIdentity: 관련된 iCloud 계정을 가지고 있는가?
var hasVideo: Bool { get set } //CXCallUpdate: 콜에 비디오가 포함되어 있는가?

has + 과거분사

모든 케이스를 통틀어 가장 덜 쓰이는 케이스 같으므로 만약 이해 안되더라도 넘어가도 지장 없다. 게다가 is + 과거분사와 뜻이 거의 같기 때문에 꼭 알아야할 필요도 없어보인다.

이때의 과거분사는 아까 is + 과거분사 때와는 다른 의미이다. has + 과거분사는 현재완료 의 의미를 가지는데 굳이 해석하자면 ‘과거에 완료된 것이 현재까지 유지되고 있다’는 뜻이다. 따라서 Bool 변수로 쓰이면 ‘~가 유지되고 있는가?’ 라고 해석할 수 있다.

var hasConnected: Bool { get } //CXCall: 콜이 연결되어 있는가?
var hasEnded: Bool { get } //CXCall: 콜이 끝났는가?

근데 isConnected, isEnded로 해도 의미가 비슷하다. 영어로 미묘한 느낌적인 차이가 있긴 하지만 수능을 다시 볼게 아니라면 꼭 알아야하는 건 아니라고 생각한다.

동사원형 용법

Bool 변수 짓기의 끝판왕이라는 생각에 마지막에 넣었다. 이거까지 잘 쓸 줄 알면 원어민 개발자 부러워하지 않아도 된다. (지극히 개인적인 의견)

주의할 점은 동사원형을 3인칭 단수로 써야한다는 것이다. 3인칭 단수는 보통 동사원형 뒤에 -s나 -es가 붙는 형태이다. Cocoa Touch에서 자주 쓰이는 단어들을 보면,

• supports: ~을 지원하는가?
• includes: ~을 포함하는가?
• shows: ~을 보여줄 것인가?
• allows: ~을 허용할 것인가?
• accepts: ~을 받아 주는가?
• contains: ~을 포함하고 있는가?

등이 있다. 이정도 단어들의 쓰임새만 알아도 풍부한 Bool 변수명을 짓기에 충분한 것 같다.

var supportsVideo: Bool //CXProviderConfiguration: 비디오를 지원하는가?
var includesCallsInRecents: Bool //CXProviderConfiguration
var showsBackgroundLocationIndicator: Bool //CLLocationManager
var allowsEditing: Bool //CNContactViewController: 편집을 허용하는가?
var acceptsFirstResponder: Bool //NSResponder

그 외에도 returns, preserves 등도 있었다.

var preservesSuperviewLayoutMargins: Bool //UIView
var returnsObjectsAsFaults: Bool //NSFetchRequest

하지만 3인칭 단수가 아닌 경우도 있다. 꽤나 예외적인 경우로 판단되기 때문에 이 역시 이해가 안되더라도 그냥 넘어가도 무방하다.

//Core Location의 CLRegion 
var notifyOnEntry: Bool { get set }
var notifyOnExit: Bool { get set }

유저의 기기가 해당 region을 벗어나거나 진입할 때 delegate를 통해 노티피케이션을 받을지 말지를 나타내는 Bool 값이다. 이 경우 notifies가 아닌 동사원형 그대로 쓰인 이유는 region 인스턴스가 notify를 하는 주체가 아니기 때문이다. 만약 notifies로 썼다면 region 인스턴스가 노티를 준다는 뜻인데 이는 맞지 않다. (아마도 CLLocationManager가 노티를 주지 않을까. 아무튼 region 인스턴스가 notify를 하는 주체가 아니기 때문에 3인칭 단수를 쓰지 않았다.)

3인칭 단수가 중요한 이유

코드 한 줄을 하나의 문장으로 비유하면 주어 역할을 하는 인스턴스가 3인칭 단수이기 때문에 문법적으로 꼭 써야하는 이유도 있지만, 3인칭 단수로 쓰지 않을 경우 스위프트 API 디자인 가이드와의 일관성이 깨져서 코드를 읽는 사람을 혼란에 빠뜨릴 수 있다. 가이드에 따르면 mutating 함수는 동사원형으로, nonmutating 함수는 동사 뒤에 -ed나 -ing를 붙여서 쓴다.

친숙한 예시로 Array의 sort()와 sorted()를 생각하면 된다.

mutating func sort() -> Void //in-place sort
func sorted() -> [Element] //정렬된 새 배열을 리턴

가령,

let overlaps: Bool = region1.overlaps(region2) //region1과 region2가 겹치는가?
region1.overlap(region2) //region1을 region2와 겹치는 부분으로 mutate
let region3 = region1.overlapping(region2) //region1과 region2가 겹치는 부분만 새로운 region 인스턴스로 리턴

이런 식으로 각각 Bool, mutating, nonmutating 함수의 이름을 지어줘야 가독성을 해치지 않고, 영문법적으로도 올바르고, 가이드에 충실한 네이밍을 할 수 있다.

마무리

정리하자면

• is 용법
  • is + 명사
  • is + 현재진행(~ing)
  • is + 형용사
  • is + 동사원형 (절대 쓰면 안됨)
• 조동사 용법
  • can, should, will 등
  • 조동사 + 동사원형
• has 용법
  • has + 명사
  • has + 과거분사 (is + 과거분사와 의미 거의 동일)
• 동사원형 용법
  • 3인칭 단수

Reference 

https://soojin.ro/blog/naming-boolean-variables

dependencies  설치 과정에서 생기는 경고창이다.

로그 내용 대로 직역 하자면 사용하고 있는 라이브러리에서 취약점이 48개가 확인되었고

npm audit fix 명령 통해 감사를 수정 하거나 강제 하거나.. 뭐 이런 내용인데 

dependencies 모두 업데이트 하더라도 모든 경고는 없애주기는 쉽지 않은 것으로 알고 있다.

글을 찾아 보니 npm v6가 나오면서 npm audit 이라는 기능이 추가 되어

npm 설치 과정 중 모듈의 취약점을 검사해 준다고 한다.

npm install 과정에서 해당 검사 과정이 필요없다면 과감히 no audit 명령어를 사용해도 좋다.

npm install --no--audit

자 그럼 위 취약점 문제들은 dependencies의 버전 업데이트 만으로도 최소화 시킬 수 있으니

npm-check-updates 기능을 활용하여 버전 관리를 진행해보자.

해당 패키지는 package.json dependencies 최신 버전으로 전체 관리 해준다.

자 그럼 아래 명령어를 통해 설치를 진행 해보자

npm install -g npm-check-updates

설치가 정상 적으로 되었다면 아래 커맨드를 실행하여 출력 값을 확인 해보자

ncu -u

해당 명령어를 실행 하면 dependencies 최신 버전이 존재하는지 확인하고 업데이트 까지 진행 해준다.

자.. 이제 dependencies 버전 관리를 한땀한땀 update 하는 수고를 덜 었다.

또한 디렉토리 package.json 파일을 확인해보면 수정 된 dependencies 버전 정보를 확인 할 수 있을 것 이다.

자세한 내용은 아래 링크에서도 확인 가능하다.

Reference

• https://github.com/raineorshine/npm-check-updates

1. Temp 폴더

C:\Users\[사용자ID]\AppData\Local

2. 두번째 Temp 폴더

경로 : C:\Windows\Temp

설명 : 씰데없는 파일들.(현재 열려있는 파일은 지워지지 않는데 그냥 건너뛰기 하세요)

3. DLL캐쉬 폴더

경로 :  C:\WINDOWS\system32\dllcache

설명 : 윈도우 설치 초기 관련 파일들이 있는 곳인데 삭제해도 무방

4. 오피스 설치 파일 폴더

경로 : C:\MSOcache

설명 : 오피스(Office) 프로그램을 설치하고 나면 생기는 폴더 입니다. 더 추가로 설치할 기능이 없다면 삭제하셔도 됩니다. 

5. 윈도우 인스톨 폴더(Install Folder)

경로 : C:\windows\installer

설명 : 저 폴더를 한방에 다 지우시면 안됩니다. C:\windows\installer\$PatchCache$\Managed 이 폴더만 지우도록 합시다.

6. 디스트리뷰션 다운로드 폴더

경로 : C:\WINDOWS\SoftwareDistribution\Download

설명 : 윈도우 및 오피스군의 업데이트 파일들이 있는곳.

Secure tunnels to localhost외부에서 로컬에 접속 가능하게 하는 터널 프로그램이다.

설치하기

1. ngrok 사이트에서 다운로드 받기 _ ngrok 바로가기
2. ngrok 압축풀기
3. ngrok.exe가 설치된 경로에서 아래 명령어 실행하기

실행하기

windows

./ngrok.exe http 8080

mac or linux

./ngrok http 8080

npm으로 실행하기

npm install -g ngrok

ngrok http 8080

실행화면

Session Expire

• 한 세션은 8시간 후 만료된다.
• 회원 가입 후 아래 링크에서 AuthToken을 가져와 입력한 후 실행하면 세션 만료 없이 사용할 수 있다. _ AuthToken 가져오기

./ngrok http 8080 AuthToken값

AuthToken 추가 후 Account

테스트

참고 글https://akageun.github.io/2019/06/26/how-to-use-ngrok.htmlhttps://phoby.github.io/ngrok/

ngrok을 사용하여 이미 HTTPS를 제공하는 로컬 서버의 공용 HTTPS 주소 가져오기(무료)

여기 시나리오는 이미 https를 통해 웹 애플리케이션을 제공하는 로컬 웹 서버가 있다는 것입니다. 다른 컴퓨터/장치에서 웹 응용 프로그램에 액세스할 수 있기를 원하므로 ngrok를 사용하여 공개 URL을 제공하고 있습니다. 기본적으로 ngrok은 로컬 웹 서버가 http를 제공하고 있다고 가정하고 로컬 웹 서버에 대한 http 및 https 터널링을 모두 지원하는 공개 URL을 제공합니다. 이것은 정말 멋지지만 이미 https를 제공하고 있다면 어떻게 될까요? ngrok이 제공하는 https URL이 작동하지 않습니다.

이제 ngrok의 무료 제품에 이 기능이 포함되어 매우 간단하게 작업할 수 있게 되어 기쁩니다!

포트 4200에서 실행 중인 로컬 웹 서버가 있고 이미 SSL 인증서로 설정되어 있다고 가정해 보겠습니다(따라서 https URL을 통해 액세스할 때만 작동함).

기본 명령줄로 ngrok을 시작하는 대신:

ngrok http 4200

대신 다음 명령줄을 사용하세요.

ngrok http <https://localhost:4200>

로컬 웹 서버가 호스트 헤더에 대해 까다롭다면 다음 명령줄로 ngrok를 시작하여 이를 매핑할 수도 있습니다.

ngrok http <https://localhost:4200> -host-header="localhost:4200"

다음 오류가 발생하면 ngrok 버전이 너무 오래되어 이 최신 기능을 지원하지 않기 때문일 수 있습니다. 최신 버전을 다운로드하고 다시 시도하기만 하면 됩니다.

참조링크 :

Using ngrok to get a public HTTPS address for a local server already serving HTTPS (for free)