Springfox (specyfikacja Swagger 2.0, aktualna)
Springfox zastąpił Swagger-SpringMVC i obsługuje teraz obie specyfikacje Swagger 1.2 i 2.0. Klasy implementacji uległy zmianie, co pozwala na głębsze dostosowanie, ale wymaga trochę pracy. Dokumentacja uległa poprawie, ale musi jeszcze pewne szczegóły dodane do zaawansowanej konfiguracji. Starą odpowiedź na implementację 1.2 nadal można znaleźć poniżej.
Zależność Mavena
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.5.0</version>
</dependency>
Minimalna implementacja wygląda mniej więcej tak samo, ale teraz używa Docketklasy zamiast SwaggerSpringMvcPluginklasy:
@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();
}
}
Twoja dokumentacja interfejsu API Swagger 2.0 będzie teraz dostępna pod adresem http://myapp/v2/api-docs.
Uwaga: jeśli nie używasz Spring Boot, powinieneś dodać zależność jackson-databind. Ponieważ springfox używa jackson do wiązania danych.
Dodanie obsługi interfejsu Swagger UI jest teraz jeszcze łatwiejsze. Jeśli używasz Maven, dodaj następującą zależność dla pliku webjar interfejsu użytkownika struktury Swagger:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.5.0</version>
</dependency>
Jeśli używasz Spring Boot, Twoja aplikacja internetowa powinna automatycznie pobierać niezbędne pliki i wyświetlać interfejs użytkownika pod adresem http://myapp/swagger-ui.html(dawniej:) http://myapp/springfox. Jeśli nie używasz Spring Boot, to jak wspomina yuriy-tumakha w poniższej odpowiedzi, będziesz musiał zarejestrować program obsługi zasobów dla plików. Konfiguracja Java wygląda następująco:
@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/");
}
}
Nowa funkcja generowania dokumentacji statycznej również wygląda całkiem ładnie, chociaż sam jej nie wypróbowałem.
Swagger-SpringMVC (specyfikacja Swagger 1.2, starsza)
Dokumentacja Swagger-SpringMVC może być nieco zagmatwana, ale w rzeczywistości jest niezwykle łatwa do skonfigurowania. Najprostsza konfiguracja wymaga stworzenia SpringSwaggerConfigbeana i włączenia konfiguracji opartej na adnotacjach (co prawdopodobnie już robisz w swoim projekcie Spring MVC):
<mvc:annotation-driven/>
<bean class="com.mangofactory.swagger.configuration.SpringSwaggerConfig" />
Uważam jednak, że warto wykonać dodatkowy krok definiowania niestandardowej konfiguracji Swaggera za pomocą SwaggerSpringMvcPluginzamiast poprzedniego komponentu bean zdefiniowanego w 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();
}
}
Po uruchomieniu aplikacji powinieneś zobaczyć specyfikację API utworzoną pod adresem http://myapp/api-docs. Aby uzyskać fantazyjny interfejs Swagger UI, musisz sklonować pliki statyczne z projektu GitHub i umieścić je w swoim projekcie. Upewnij się, że projekt jest skonfigurowany do obsługi statycznych plików HTML:
<mvc:resources mapping="*.html" location="/" />
Następnie edytuj index.htmlplik na najwyższym poziomie katalogu Swagger UI dist. Na początku pliku zobaczysz JavaScript, który odwołuje się do api-docsadresu URL innego projektu. Edytuj to, aby wskazać dokumentację Swaggera projektu:
if (url && url.length > 1) {
url = url[1];
} else {
url = "http://myapp/api-docs";
}
Teraz, gdy przejdziesz do http://myapp/path/to/swagger/index.html, powinieneś zobaczyć wystąpienie interfejsu użytkownika Swagger dla swojego projektu.