springboot swagger 사용하기

서버 개발할 때 가장 중요한 일은 프론트엔드가 얼마나 보기 좋게 문서를 작성하느냐에 달려있다고 생각한다. 문서를 제대로 정리해놓지 않으면 매번 물어봐야 하고... 대화해야 하고 번거로운 일이 너무 많은데 swagger로 postman을 대신해서 사용할 수도 있고 프론트엔드와 작업하기도 편하다.

build.gradle

implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.6.6'

configs/SetupSwagger.java

package com.spring.container.spring.configs;

import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;

@Configuration
public class SetupSwagger {

  @Bean
  public GroupedOpenApi springSwagger() {
    return GroupedOpenApi.builder()
      .group("spring")
      .pathsToMatch("/**")
      .build();
  }
  @Bean
  public OpenAPI openAPI() {
    return new OpenAPI()
      .info(new Info().title("Spring swagger")
      .description("starter pack")
      .version("0.0.1"));
  }
}

dtos/BodyDto.java

package com.spring.container.spring.dtos;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Getter;
import lombok.Setter;

@Setter
@Getter
@Schema(description = "BodyDto")
public class BodyDto {
  @Schema(defaultValue = "name",description = "name")
  private String name;
  
  @Schema(defaultValue = "1",description = "id")
  private int id;
}

dtos/QueryDto.java

package com.spring.container.spring.dtos;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
@Schema(description = "QueryDto")
public class QueryDto {
  @Schema(defaultValue = "1")
  private int page;

  @Schema(defaultValue = "10")
  private int count;
}

responses/TestResponse.java
프론트엔드가 확인할 수 있는 200일 경우 response model을 정해줄 수 있습니다.

package com.spring.container.spring.responses;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Getter;

@Getter
@AllArgsConstructor
@Schema(description = "TestResponse")
public class TestResponse {
  @Schema()
  private String name;
  @Schema()
  private int id;
}

controllers/AuthController.java

package com.spring.container.spring.controllers;

import org.springframework.web.bind.annotation.RestController;

import com.spring.container.spring.dtos.BodyDto;
import com.spring.container.spring.dtos.QueryDto;
import com.spring.container.spring.responses.TestResponse;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;

import org.springdoc.api.annotations.ParameterObject;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;

@Tag(name = "auth") // tag를 달아서 그룹을 정해줄 수 있습니다.
@RestController
@RequestMapping("auth")
public class AuthController {

  @Operation(
    description = "Test api"
  )
  @ApiResponse(
    responseCode = "200",
    content = @Content(
      schema = @Schema(
        /*
         * 프론트엔드가 response를 확인하고 modeling을 할 수 있게 합니다.
         */
        implementation = TestResponse.class
      )
    )
  )
  @PostMapping(
    name = "test",
    produces = MediaType.APPLICATION_JSON_VALUE // json string -> json
  )
  public ResponseEntity<String> test(
    @ParameterObject QueryDto query, // query
    @RequestParam String uuid, // param
    @RequestBody BodyDto body // body
  ) {
    try {
      System.out.println(query.getCount());
      System.out.println(query.getPage());
      System.out.println(uuid);
      return ResponseEntity
        .status(HttpStatus.OK)
        .body("{\"name\" : \""+body.getName()+"\" , \"id\":"+body.getId()+"}");
    } catch(Exception e) {
      System.out.println(e);
      return ResponseEntity
      .status(HttpStatus.BAD_REQUEST)
      .body(null);
    }
  }
}

curl로도 표현됩니다.

이제 vscode에서 dockerize된 환경으로 개발할 준비가 끝낫습니다.

git에서 전체 코드를 확인하실 수 있습니다.
https://github.com/jjh930301/docker-springboot-starter-pack