Swagger2 Configuration - redutan/redutan.github.io GitHub Wiki

Dependencies

pom.xml

    <properties>
        ...
        <swagger2.version>2.9.0</swagger2.version>
    </properties>

    <dependencies>
        ...
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger2.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger2.version}</version>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            ...
            <dependency>
                <groupId>com.google.guava</groupId>
                <artifactId>guava</artifactId>
                <version>24.1-jre</version>
            </dependency>
        </dependencies>
    </dependencyManagement>
  • 2.9.0 λ²„μ „μœΌλ‘œ μΆ”κ°€ μ‹œ guava 버전 좩돌이 λ°œμƒν•˜λ―€λ‘œ μ˜μ‘΄μ„± μž¬μ •μ˜ μš”λ§

build.gradle

ext['springfoxVersion'] = '2.7.0'

dependencies {
    compile "io.springfox:springfox-swagger2:${springfoxVersion}"
    compile "io.springfox:springfox-swagger-ui:${springfoxVersion}"
//    compile "io.springfox.ui:springfox-swagger-ui-rfc6570:1.0.0"   // incubating
}

Swagger2Configuration.java

/**
 * Swagger2 Configuration
 *
 * @author myeongju.jung
 */
@SuppressWarnings("Guava")
@Configuration
@ConditionalOnWebApplication
@EnableSwagger2
public class Swagger2Configuration {

    @Bean
    public Docket allApi() {
        return globalConfiguration(
            new Docket(DocumentationType.SWAGGER_2)
                .groupName("Example SNS API - All")
                .apiInfo(apiInfo())
                .select()
                .paths(allApiPaths())
                .build());

    }

    private Docket globalConfiguration(Docket docket) {
        return docket
            .directModelSubstitute(ZonedDateTime.class, Long.class)
            .ignoredParameterTypes(Pageable.class, UriComponentsBuilder.class, Model.class, UserDetails.class)
            .genericModelSubstitutes(ResponseEntity.class)
            .useDefaultResponseMessages(false)
            .globalResponseMessage(RequestMethod.GET, newArrayList(
                new ResponseMessageBuilder()
                    .code(400)
                    .message("μΈμžκ°€ μœ νš¨ν•˜μ§€ μ•ŠλŠ” 경우")
                    .build(),
                new ResponseMessageBuilder()
                    .code(404)
                    .message("μ‘°νšŒν•  μžμ›μ„ 찾을 수 μ—†λŠ” 경우")
                    .build(),
                new ResponseMessageBuilder()
                    .code(500)
                    .message("Internal Server Error")
                    .build()
                                                                  ))
            .globalResponseMessage(RequestMethod.POST, newArrayList(
                new ResponseMessageBuilder()
                    .code(400)
                    .message("μΈμžκ°€ μœ νš¨ν•˜μ§€ μ•ŠλŠ” 경우")
                    .build(),
                new ResponseMessageBuilder()
                    .code(404)
                    .message("μ—°κ΄€λœ μžμ›μ„ 찾을 수 μ—†λŠ” 경우")
                    .build(),
                new ResponseMessageBuilder()
                    .code(500)
                    .message("Internal Server Error")
                    .build()
                                                                     ))
            .globalResponseMessage(RequestMethod.PUT, newArrayList(
                new ResponseMessageBuilder()
                    .code(400)
                    .message("μΈμžκ°€ μœ νš¨ν•˜μ§€ μ•ŠλŠ” 경우")
                    .build(),
                new ResponseMessageBuilder()
                    .code(404)
                    .message("λ³€κ²½ν•  μžμ›μ„ 찾을 수 μ—†λŠ” 경우")
                    .build(),
                new ResponseMessageBuilder()
                    .code(500)
                    .message("Internal Server Error")
                    .build()
                                                                  ))
            .globalResponseMessage(RequestMethod.DELETE, newArrayList(
                new ResponseMessageBuilder()
                    .code(400)
                    .message("μΈμžκ°€ μœ νš¨ν•˜μ§€ μ•ŠλŠ” 경우")
                    .build(),
                new ResponseMessageBuilder()
                    .code(404)
                    .message("μ‚­μ œν•  μžμ›μ„ 찾을 수 μ—†λŠ” 경우")
                    .build(),
                new ResponseMessageBuilder()
                    .code(500)
                    .message("Internal Server Error")
                    .build()
                                                                  ))
            ;
    }

    private Predicate<String> allApiPaths() {
        return not(or(
            regex("/management.*"),
            regex("/error.*")
                     ));
    }

    @Bean
    public Docket postApi() {
        return globalConfiguration(
            new Docket(DocumentationType.SWAGGER_2)
                .groupName("Example SNS API - Post")
                .apiInfo(apiInfo())
                .select()
                .paths(postApiPaths())
                .build());
    }

    private Predicate<String> postApiPaths() {
        return or(
            regex("/posts.*"),
            regex("/recommend-posts.*"),
                 );
    }

    @Bean
    public Docket userApi() {
        return globalConfiguration(
            new Docket(DocumentationType.SWAGGER_2)
                .groupName("Example SNS API - User")
                .apiInfo(apiInfo())
                .select()
                .paths(userApiPaths())
                .build());
    }

    private Predicate<String> userApiPaths() {
        return or(
            regex("/user.*"),
            regex("/post\\-users.*")
                 );
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("Example SNS API")
            .description("μ μ ˆν•œ μ„€λͺ… 블라블라. html νƒœκ·ΈλŠ” μ‚¬μš©ν•  수 μ—†μŒ")
            .termsOfServiceUrl("http://example-sns.co.kr")
            .contact(new Contact("Example SNS κ°œλ°œνŒ€", "http://corp.example-sns.co.kr", "[email protected]"))
            .build();
    }
}

UserController.java

@Api(tags = "user", description = "μ‚¬μš©μž")
@RestController
@RequestMapping("/users")
public class UserRestController {
    @Autowired
    private UserService userService;

    /**
     * μ‚¬μš©μžλ“€ νŽ˜μ΄μ§• 쑰회
     */
    @ApiOperation("μ‚¬μš©μžλ“€ νŽ˜μ΄μ§• 쑰회")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "page", value = "νŽ˜μ΄μ§€ 번호(0base)", required = false, defaultValue = "0", dataType = "number", paramType = "query"),
        @ApiImplicitParam(name = "size", value = "νŽ˜μ΄μ§€ λ‹Ή μ‚¬μ΄μ¦ˆ", required = false, defaultValue = "10", dataType = "number", paramType = "query")
    })
    @GetMapping("")
    public Page<UserRowDto> list(UserSearch search,
                                 @PageableDefault Pageable pageable) {
        return userService.getUserRows(search, pageable);
    }

    /**
     * μ‚¬μš©μž 1건 상세 쑰회
     */
    @ApiOperation(value = "μ‚¬μš©μž 상세 쑰회")
    @GetMapping("/{userId}")
    public UserDetail detail(@ApiParam(value = "μ‚¬μš©μžμ•„μ΄λ””", required = true) @PathVariable("userId") String userId) {
        return userService.getUserDetail(userId);
    }

    /**
     * μ‚¬μš©μž μ†Œκ°œκΈ€ λ³€κ²½
     */
    @ApiOperation(value = "μ‚¬μš©μž μ†Œκ°œκΈ€ λ³€κ²½")
    @PutMapping("/{userId}/introduction")
    public void modifyIntroduction(@ApiParam(value = "μ‚¬μš©μžμ•„μ΄λ””", required = true) @PathVariable("userId") String userId,
                                   @Valid @RequestBody UserIntroduction input) {
        userService.modifyIntroduction(userId, input.getValue());
    }

    /**
     * νŽ˜μ΄μ§€ μ‹ μ²­
     */
    @ApiOperation(value = "νŽ˜μ΄μ§€ μ‹ μ²­", notes = "μΆ”ν›„ νŽ˜μ΄μ§€κ°€ μŠΉμΈν•˜λ©΄ 정식 κ΄€λ¦¬μžλ‘œμ¨ ν™œμ„±ν™”. 볡수 신청해도 λ©±λ“±μ„±μœΌλ‘œ 인해 νŽ˜μ΄μ§€ 신청이 μΈκ°€λœλ‹€.")
    @ApiResponses({
        @ApiResponse(code = 403, message = "νŽ˜μ΄μ§€λ₯Ό μ‹ μ²­ν•  수 μ—†λŠ” μƒνƒœμΈ 경우 (휴면, λΈ”λž™ λ“±)", response = ErrorModel.class),
        @ApiResponse(code = 404, message = "νšŒμ›μ΄ μ‘΄μž¬ν•˜μ§€ μ•Šκ±°λ‚˜ νƒˆν‡΄λœ 경우 λ°œμƒ", response = ErrorModel.class),
        @ApiResponse(code = 409, message = "일반적으둜 이미 μ‘΄μž¬ν•˜λŠ” νŽ˜μ΄μ§€μΈ 경우", response = ErrorModel.class)
    })
    @PostMapping("/pages")
    public ResponseEntity createPage(PageCreateRequest param, UriComponentsBuilder uriComponentsBuilder,
                                     @AuthenticationPrincipal UserDetails) {
        Page page = pageService.request(param, userDetails);
        URI location = getLocation(page, uriComponentsBuilder);
        return ResponseEntity.created(location).build();
    }

    private URI getLocation(Page page, UriComponentsBuilder uriComponentsBuilder) {
        return uriComponentsBuilder.path("/pages/{pageId}/")
                                   .buildAndExpand(page.getPageId())
                                   .toUri();
    }
}
⚠️ **GitHub.com Fallback** ⚠️