Swagger2 Configuration - redutan/redutan.github.io GitHub Wiki
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
}
/**
* 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();
}
}
@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();
}
}