intellij spring boot 협업시 개발 환경 통일 하기 - 코드 컨벤션, Exception 처리, rest API 구조 설계, swagger API 문서화 - 1

1. 코드 컨벤션

코드 컨벤션이란?

특정 프로그래밍 언어에 대한 프로그래밍 스타일, 관행 및 방법을 권장하는 일련의 지침

왜 코드 컨벤션을 정해야할까?

1. 일단 가장 큰 이유는 유지보수이다. 코드 큐칙은 소프트웨어의 가독성을 높인다. 전체 일관된 코드 스타일을 유지하여 협업에 용이하고 깨끗한 코드를 만들 수 있다!

2. 협업시 꼭 코드 컨벤션을 정해야하는 이유는 각자 코드 스타일을 다르기 때문이다. 인텔리제이에 Reformat Code라는 기능이 있다. 코드 컨벤션에 맞게 변경해주는 굉장히 편한 기능이다! -> 따라서 이걸 써주기 위해 팀원과 코드 스타일을 통일 시켜야한다.

intellij 적용 방법

1. 코딩 컨벤션을 다운 받는다

https://naver.github.io/hackday-conventions-java/#_intellij

https://github.com/naver/hackday-conventions-java/blob/master/rule-config/naver-intellij-formatter.xml
네이버 코딩 컨벤션이다.
깃허브에서 xml 파일을 다운받거나 xml 파일을 만들어줘서 내용을 복붙한다.

2. IDE 적용

preferences -> Editor -> code style

다운받은 xml 파일 적용

출처 - https://055055.tistory.com/97

2. Swagger 연동

API를 개발할때 프론트와 원활한 소통을 위해서는 API 명세서가 필수이다. 명세서를 작성하는 여러가지 방법이 있는데 그 중 API 문서화를 자동으로 해주는 Swagger를 사용해보도록 하자.

Swagger 버전 3은 기존에 쓰던 어노테이션이 많이 바꼈다.

maven

	<dependency>
		<groupId>org.springdoc</groupId>
		<artifactId>springdoc-openapi-ui</artifactId>
		<version>1.4.6</version>
	</dependency>
    

gradle

implementation 'org.springdoc:springdoc-openapi-ui:1.5.7'

사용방법

사용방법은 간단하다. 어노테이션을 이용해서 원하는 설명을 적으면 된다. 주로 컨트롤러에 무슨 역할을 하는 컨트롤러인지, HTTP 메서드의 역할, 필요한 파라미터가 무엇인지, 파라미터 값 설명을 입력한다

swagger 2와 3의 차이점

2에서 3으로 변화하면서 달라진 어노테이션들이다.

//어노테이션 변경
@ApiParam -> @Parameter
@ApiOperation -> @Operation
@Api -> @Tag
@ApiImplicitParams -> @Parameters
@ApiImplicitParam -> @Parameter
@ApiIgnore -> @Parameter(hidden = true) or @operation(hidden = true) or @hidden
@apimodel -> @Schema
@ApiModelProperty -> @Schema

//파라미터 변경
value -> description
tags -> name

출처 - https://velog.io/@hyejinjeong9999/springdoc으로-swagger3-도입