Documentation 작성법 ; Swagger, Javadocs, Markdown

API Dcoumentation 작성

목적 : 프론트엔드 개발자와 동료 백엔드 개발자에게 내가 생성한 API가 어떻게 동작하는지 설명함.

문서화방식 : txt파일로 생성시에, 최신화 및 문서버전관리가 어려워 swagger 등 와 같은 전용툴을 사용함.

Swagger

Swagger는 RESTful API 문서를 자동으로 생성해주는 오픈소스 툴입니다. API 개발자와 클라이언트(프론트엔드, 모바일 개발자) 간의 API 명세 공유 및 테스트를 쉽게 할 수 있도록 도와줍니다.

Url형식으로 배포해주기 때문에 공유에 유리함
API 요청/응답 데이터 확인 가능
API 명세서(Documentation) 자동 생성

Swagger에서 추가적으로 설정할 수 있는 것들

✅ API 기본 정보 (@OpenAPIDefinition, @Info, @Contact)
✅ JWT 인증 적용 (@SecurityScheme, @SecurityRequirement)
✅ DTO 필드 설명 (@Schema)
✅ API 응답 코드 설명 (@ApiResponses)
✅ 페이징 처리 (@PageableAsQueryParam)
✅ Enum 값 설명 (@Schema)
✅ 응답 예제 설정 (@ExampleObject)
✅ API 그룹 나누기 (@Tag)
✅ 파일 업로드 (Multipart)

1. 스프링 환경설정

Spring 3.0 이후와 호환성고려한 버전 선택

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.5'

Swagger UI URL

Spring Boot에서는 http://localhost:8080/swagger-ui.html에서 접근 가능

2. Swagger 관련 Bean 등록

아래의 경우에 커스터마이징하는 경우에만 사용

API 명세에 추가적인 정보 (title, description 등) 설정
JWT 인증 헤더 추가
API 그룹화 (tags, paths 분리) 설정
서버 URL 커스터마이징
JWT 인증을 추가하는 경우

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.servers.Server;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

        @Bean
        public OpenAPI customOpenAPI() {
                return new OpenAPI()
                        .addServersItem(new Server().url("https://api.example.com").description("Production Server"))
                        .info(new Info()
                                .title("My API")
                                .version("1.0")
                                .description("This is a sample API for demonstration purposes"));
        }
}

@Configuration
public class OpenApiSecurityConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info().title("My API").version("1.0").description("JWT 인증이 포함된 API 문서"))
                .addSecurityItem(new SecurityRequirement().addList("JWT"))
                .components(new io.swagger.v3.oas.models.Components()
                        .addSecuritySchemes("JWT",
                                new SecurityScheme()
                                        .name("Authorization")
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")));
    }
}

3. Swagger 관련 어노테이션

Swagger에서는 OpenAPI 3.0 표준을 따르며, 주로 다음 어노테이션을 사용합니다.

Congifuration 설정

Security 설정

Controller 전체 설정

@Slf4j
@RestController
@RequestMapping(path = "/auth")
@RequiredArgsConstructor
@Tag(name = "인증 & 로그인 관련 API", description = "인증 & 로그인 관련 API")
public class AuthController {

@Tag(name, description)
- 특정 API들을 그룹별로 나누어 문서를 관리할 수 있습니다
  - 그룹화란, 하나의 컨트롤러를 페이지 단위로 하여 접고 닫을수 있는 카테고리로 생성

Controller 내 메소드(API) 설정

@GetMapping(path = "/company/list/{companyId}")
@Operation(
        summary = "회사 소속의 유저정보 확인",
        description = "회사 소속의 유저정보 확인"
)
@Parameter(name = "companyId", description = "회사명")
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "조회 성공",
                content = @Content(
                        mediaType = MediaType.APPLICATION_JSON_VALUE,
                        array = @ArraySchema(schema = @Schema(implementation = UserDto.UserResDto.class))
                )
        ),
        @ApiResponse(responseCode = "400", description = "잘못된 요청",
                content = @Content(schema = @Schema(implementation = ApiResponseDto.class))),
        @ApiResponse(responseCode = "500", description = "서버 에러 발생",
                content = @Content(schema = @Schema(implementation = ApiResponseDto.class))),
})
public ResponseEntity<ApiResponseDto<List<UserDto.UserResDto>>> getUserByCompanyId(@PathVariable("companyId") String companyId) {
    List<UserDto.UserResDto> userResDtoList =  userService.findUserByCompanyId(companyId);
    return ResponseEntity.ok().body(ApiResponseDto.makeSuccessResponse(userResDtoList));
}

@Operation(summary, description)
- 컨트롤러 내 메소드에서 api 별로 제목과 설명을 추가할 수 있음
@Parameter(name, description)
- API 요청의 개별 파라미터(경로 변수, 쿼리 파라미터 등)에 대한 설명을 추가합니다.
- Request Body에 대한 설명을 추가하려면 @Schema 또는 @RequestBody를 사용해야 함.

@PostMapping(path = "/refresh")
@Operation(
        summary = "Access Token 갱신",
        description = "Refresh Token 을 이용한 Access Token 갱신"
)
@ApiResponses({
        @ApiResponse(responseCode = "200", description = "요청 성공",
                content = @Content(schema = @Schema(implementation = LoginDto.LoginResDto.class))),
        @ApiResponse(responseCode = "400", description = "잘못된 요청",
                content = @Content(schema = @Schema(implementation = ApiResponseDto.class))),
        @ApiResponse(responseCode = "500", description = "서버 에러 발생",
                content = @Content(schema = @Schema(implementation = ApiResponseDto.class))),
})
public ResponseEntity<ApiResponseDto<LoginDto.LoginResDto>> refreshToken(@io.swagger.v3.oas.annotations.parameters.RequestBody(description = "Refresh Token 요청 DTO") @RequestBody @Valid LoginDto.RefreshTokenReqDto dto) {
    LoginDto.LoginResDto resDto = loginService.refreshAccessToken(dto);
    return ResponseEntity.ok().body(ApiResponseDto.makeSuccessResponse(resDto));
}

@io.swagger.v3.oas.annotations.parameters.RequestBody(description = "string") : API의 Request Body에 대한 추가적인 문서 설명을 제공
- 예시응답은 @RequestBody를 사용하는 경우, 자동으로 해당 DTO 클래스의 필드명과 타입을 기반으로 예시 응답(Example Value)을 생성

API Responses 설정

@ApiResponses({
        @ApiResponse(responseCode = "200", description = "조회 성공",
                content = @Content(
                        mediaType = MediaType.APPLICATION_JSON_VALUE,
                        array = @ArraySchema(schema = @Schema(implementation = AuthorityDto.AuthListResDto.class))
                )
        ),
        @ApiResponse(responseCode = "400", description = "잘못된 요청",
                content = @Content(schema = @Schema(implementation = ApiResponseDto.class))),
        @ApiResponse(responseCode = "500", description = "서버 에러 발생",
                content = @Content(schema = @Schema(implementation = ApiResponseDto.class))),
})

@ApiResponses({ ... }) : @ApiResponses 애노테이션은 **Swagger (Springdoc OpenAPI)**에서 API의 응답을 문서화할 때 사용.
- 특히, 여러 개의 @ApiResponse를 그룹화하여 한 번에 적용

@ApiResponse(responseCode, description) :특정 HTTP 응답 코드에 대한 문서화를 담당합니다.
- mediaType = MediaType.APPLICATION_JSON_VALUE
- @Content(schema = @Schema(...)) : 응답 본문의 구조를 정의
  - @Schema(implementation = DTO.class) : 응답 본문의 구조를 DTO 기반으로 지정
- @Content(schema = @Schema(...)) : 응답 본문의 구조를 정의
  - @ArraySchema는 응답 데이터가 배열일 경우 사용합니다.
  - mediaType은 API가 응답할 데이터의 **미디어 타입(컨텐츠 타입, Content-Type)**을 지정합니다.

DTO설정

   @Getter
    @NoArgsConstructor
    @Schema(description = "변경 할 비밀번호 DTO")
    public static class ChangePasswordReqDto {
        @Schema(description = "이메일")
        @NotBlank(message = "이메일 정보는 필수입니다.")
        private String email;
        @Schema(description = "변경할 비밀번호")
        @NotBlank(message = "변경할 비밀번호 입력은 필수입니다.")
        private String password;
    }

    // ============================================================================

    @Getter
    @Builder
    @Schema(description = "로그인 응답 DTO")
    public static class LoginResDto {
        @Schema(description = "Access Token")
        private String accessToken;
        @Schema(description = "refresh Token")
        private String refreshToken;
    }
}

@Schema(description = "DTO 설명") : 하단 Schemas 탭에서 확인 가능.
- @Schema를 DTO에 추가하는 것은 Swagger UI 하단의 "Schemas" 섹션을 위한 것입니다. @Schema는 Swagger 문서에서 DTO의 구조를 명확하게 설명하기 위한 용도
- @Schema(example = "변상화")을 설정해서 "Example Value"에도 영향을 줄 수 있음

JavaDoc

Swagger UI는 REST API 문서를 자동 생성 라면 JavaDoc은 Java 코드에 대한 공식적인 문서를 생성하는 도구. 즉, Javadoc은 주로 Java 내부 코드(클래스, 메서드, 변수 등)를 문서화하는 데 사용됨.

태그	설명	사 대상
@param	메서드 매개변수 설명	메서드
@return	반환값 설명	메서드
@throws	발생할 수 있는 예외 설명	메서드
@author	작성자 이름	클래스

Javadoc 주석 : /** ... */ 형식의 특별한 주석을 사용하여 문서를 작성합니다.
- 주석내에 일반적으로 작성되는 것은 description으로 분류

특정 클래스가 주소하는 위치에서 클래스를 문서화함

javadoc -d docs Calculator.java

단, javadoc으로 직접 터미널을 사용하면 spring 등과 같은 외부의존성을 찾지 못하는 문제가 발생하므로, javadoc을 사용하기 보다는 gradlew을 사용하여 javadoc을 사용한다.

Gradle의 javadoc 태스크(task)를 실행하는 명령어 즉, Gradle이 제공하는 Javadoc 생성 기능을 실행하는 것임. 해당 기능은 java plugin을 적용하면 실행됨.

./gradlew javadoc

Readme 작성

Markdown 이란?

일반 텍스트 형식의 문서의 양식을 편집하는 문법 누구나 쉽게읽고 쓸수있으며 완성후 HTML으로 쉽게 변환되어 보여진다. 특수기호와 문자를 이용한 매우 간단한 구조의 문법을 사용해 빠르게 작성하고 쉽게 읽을 수 있다. StackOverflow, Discord, Reddit, GitHub에서 두루두루 사용됨.

Markdown 태그의 종류

-제목 h1 : #,=====
- 소제목 h2 : ##
- 소제목 h3 : ###
- 가로경계선 생성 : ----- , ***** , +++++
- UnorderedList : -
- Indented Unordered List : (blank space) -

- 볼드체 : **내용**

- 이탤릭체 :

-인용 : >
-강조:*,_

- 링크 : [텍스트](주소 "설명 생략가능")
- 이미지 : ![텍스트](이미지주소 "설명 생략가능") -리스트:1,*,-,+

- 코드표시 : <code>코드</code> , 한줄 띄우고 스페이스 4칸 , ```코드``` -줄바꿈:엔터2번,강제줄바꿈은문장끝에스페이스바2칸

“프로젝트를 설명하는 문서”

어떠한 목적으로 개발되었는지, 코드의 개요, 코드의 구조, 빌드 방법, 사용법 등을 마크다운으로 작성한다.

마크다운문법 공식문서 : https://www.markdownguide.org/

프로젝트 구성
프로젝트 프로그램 설치방법
프로젝트 프로그램 사용법
저작권 및 사용권 정보
프로그래머 정보
버그 및 디버그
참고 및 출처
버전 및 업데이트 정보
FAQ

https://backendcode.tistory.com/165

https://medium.com/@ruccess0.0/readme-%EC%93%B0%EB%8A%94%EB%B2%95-380a8b6c78b5

https://velog.io/@luna7182/%EB%B0%B1%EC%97%94%EB%93%9C-%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8-README-%EC%93%B0%EB%8A%94-%EB%B2%95

'개발 프로젝트 > 협업 관련 툴' 카테고리의 다른 글

Github Issue (0)	2025.03.10
Flowchart 작성하기 (0)	2024.11.15
Git, GitHub 그리고 Commit (0)	2024.09.16

생각정리, 개발정리

Documentation 작성법 ; Swagger, Javadocs, Markdown

API Dcoumentation 작성

Swagger

JavaDoc

Readme 작성

'개발 프로젝트 > 협업 관련 툴' 카테고리의 다른 글

티스토리툴바

Documentation 작성법 ; Swagger, Javadocs, Markdown

API Dcoumentation 작성

Swagger

JavaDoc

Readme 작성

'개발 프로젝트 > 협업 관련 툴' 카테고리의 다른 글

'개발 프로젝트/협업 관련 툴' Related Articles

티스토리툴바