Perché non usare Swagger in correlazione con la codifica? La documentazione è sempre nella versione attuale, non è necessario mantenerla, è possibile testarla - molti vantaggi in questo tipo di approccio. È semplice integrare Swagger con Spring MVC. Inizia con l'API ( non hai bisogno di implementare nulla ), quindi in Spring MVC sarebbe il livello dei controller e lo userà come scheletro per la tua app. Qui hai una configurazione per Swagger che usa Docker - wrapper per swagger api.
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage(
"com.example.controllers"))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
ApiInfo apiInfo = new ApiInfo(
"Info ...",
"Info ...",
"Version ...",
"",
new Contact("John Smith", "",
"[email protected]"),
"Copyright 2017 John Smith",
"");
return apiInfo;
}
}
E due dipendenze, assumendo che tu usi Maven
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0/version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
Dopo aver creato e distribuito l'app, i documenti Swagger sarebbero disponibili
YOUR_SERVER:PORT/swagger-ui.html#/
E esempio di utilizzo nel controller
@ApiOperation(value = "Register user")
@RequestMapping(value = "/users", method = RequestMethod.POST, produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
@ResponseStatus(HttpStatus.CREATED)
public void registerUser(@RequestBody @Valid NewUserRequest newUserRequest) {
// you don't need to implement it now
}