Springfox (Swagger spec 2.0, attuale)
Springfox ha sostituito Swagger-SpringMVC e ora supporta entrambe le specifiche Swagger 1.2 e 2.0. Le classi di implementazione sono cambiate, consentendo una personalizzazione più profonda, ma con un po 'di lavoro. La documentazione è migliorata, ma necessita ancora di alcuni dettagli aggiunti per la configurazione avanzata. La vecchia risposta per l'implementazione 1.2 può ancora essere trovata di seguito.
Dipendenza da Maven
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
L'implementazione del minimo indispensabile sembra più o meno la stessa, ma ora utilizza la Docketclasse anziché la SwaggerSpringMvcPluginclasse:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api(){
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.regex("/api/.*"))
.build()
.apiInfo(apiInfo());
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("TITLE")
.description("DESCRIPTION")
.version("VERSION")
.termsOfServiceUrl("http://terms-of-services.url")
.license("LICENSE")
.licenseUrl("http://url-to-license.com")
.build();
}
}
La documentazione relativa all'API Swagger 2.0 sarà ora disponibile all'indirizzo http://myapp/v2/api-docs.
Nota: se non si utilizza Spring Boot, è necessario aggiungere la dipendenza jackson-databind. Poiché springfox utilizza jackson per l'associazione dati.
Aggiungere il supporto dell'interfaccia utente Swagger ora è ancora più semplice. Se stai usando Maven, aggiungi la seguente dipendenza per il webjar dell'interfaccia utente di Swagger:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
Se stai usando Spring Boot, la tua app web dovrebbe raccogliere automaticamente i file necessari e mostrare l'interfaccia utente in http://myapp/swagger-ui.html(in precedenza:) http://myapp/springfox. Se non stai usando Spring Boot, come menzionato da yuriy-tumakha nella risposta di seguito, dovrai registrare un gestore di risorse per i file. La configurazione Java è simile a questa:
@Configuration
@EnableWebMvc
public class WebAppConfig extends WebMvcConfigurerAdapter {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
Anche la nuova funzionalità di generazione della documentazione statica sembra abbastanza carina, anche se non l'ho provata io stesso.
Swagger-SpringMVC (Swagger spec 1.2, precedente)
La documentazione per Swagger-SpringMVC può essere un po 'confusa, ma in realtà è incredibilmente facile da configurare. La configurazione più semplice richiede la creazione di un SpringSwaggerConfigbean e l'abilitazione della configurazione basata sull'annotazione (cosa che probabilmente fai già nel tuo progetto Spring MVC):
<mvc:annotation-driven/>
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
Tuttavia, penso che valga la pena fare il passo in più per definire una configurazione Swagger personalizzata utilizzando SwaggerSpringMvcPlugin, invece del precedente bean definito da XML:
@Configuration
@EnableSwagger
@EnableWebMvc
public class SwaggerConfig {
private SpringSwaggerConfig springSwaggerConfig;
@SuppressWarnings("SpringJavaAutowiringInspection")
@Autowired
public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
this.springSwaggerConfig = springSwaggerConfig;
}
@Bean
public SwaggerSpringMvcPlugin customImplementation(){
return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
.apiInfo(apiInfo())
.includePatterns(".*api.*");
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("TITLE")
.description("DESCRIPTION")
.version("VERSION")
.termsOfServiceUrl("http://terms-of-services.url")
.license("LICENSE")
.licenseUrl("http://url-to-license.com")
.build();
}
}
Quando esegui la tua applicazione, ora dovresti vedere la tua specifica API creata in http://myapp/api-docs. Per ottenere la fantastica interfaccia utente Swagger, è necessario clonare i file statici dal progetto GitHub e inserirli nel progetto. Assicurati che il tuo progetto sia configurato per servire i file HTML statici:
<mvc:resources mapping="*.html" location="/" />
Quindi modifica il index.htmlfile al livello superiore della distdirectory dell'interfaccia utente di Swagger . Verso l'inizio del file, vedrai alcuni JavaScript che si riferiscono api-docsall'URL di un altro progetto. Modificalo per puntare alla documentazione Swagger del tuo progetto:
if (url && url.length > 1) {
url = url[1];
} else {
url = "http://myapp/api-docs";
}
Quando navighi a http://myapp/path/to/swagger/index.html, dovresti vedere l'istanza dell'interfaccia utente di Swagger per il tuo progetto.