主要作用：给接口调用者提供接口描述（类似于webservice的WSDL一样，对提供的服务接口进行描述）。描述中包括请求方式、url、参数等细节，swagger提供默认的UI实现，开发人员可以像postman一样模拟请求。
1.swagger目前版本为2.0，在swagger1中核心jar包为com.mangofactory提供的swagger-springmvc
2.0版可结合springfox使用，相关依赖如下：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2.配置类代码：
@Configuration
@EnableWebMvc
@EnableSwagger2
@ComponentScan(basePackages = { "com.wallet.web.rest.controller" })
public class SwaggerConfig extends WebMvcConfigurerAdapter {
@Bean
public Docket customDocket() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
.paths(paths())
.build()
.pathMapping("/");
}
private Predicate<String> paths() {
return PathSelectors.any();
}
private ApiInfo apiInfo() {
Contact contact = new Contact("货代钱包", "https://www.huodaipay.com", "400-168-5620");
return new ApiInfoBuilder().title("API接口").description("API接口").contact(contact).version("1.0.0").build();
}
@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/");
}
@Override
public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
ObjectMapper objectMapper = null;
for (HttpMessageConverter converter : converters) {
if (converter instanceof MappingJackson2HttpMessageConverter) {
MappingJackson2HttpMessageConverter jacksonConverter =
((MappingJackson2HttpMessageConverter) converter);
if (objectMapper == null) {
objectMapper = jacksonConverter.getObjectMapper();
} else {
jacksonConverter.setObjectMapper(objectMapper);
}
}
}
}
}
3.配置文件
<!-- Required so springfox can access spring's RequestMappingHandlerMapping --> <mvc:annotation-driven/> <!-- Required to enable Spring post processing on @Configuration classes. --> <context:annotation-config/>
注：如果配置了context:component-scan，这个配置可以忽略
<!-- Loads the spring beans required by the framework --> <bean class="<bean class="com.gao.config.SwaggerConfig"/>"/>
注：这句必须配置，否则报错
org.springframework.web.util.NestedServletException: Request processing failed; nested exception is java.lang.IllegalArgumentException: No converter found for return value of type: class springfox.documentation.spring.web.json.Json org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:982) org.springframework.web.servlet.FrameworkServlet.doGet(FrameworkServlet.java:861) javax.servlet.http.HttpServlet.service(HttpServlet.java:622) org.springframework.web.servlet.FrameworkServlet.service(FrameworkServlet.java:846) javax.servlet.http.HttpServlet.service(HttpServlet.java:729) org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52) com.wallet.web.rest.filter.DangerFilter.doFilterInternal(DangerFilter.java:29) org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107) org.springframework.web.filter.CharacterEncodingFilter.doFilterInternal(CharacterEncodingFilter.java:197) org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:107)
报这个错误时 http://localhost:8070/swagger-ui.html 也无法查看，报错：
Unable to infer base url. This is common when using dynamic servlet registration or when the API is behind an API Gateway. The base url is the root of where all the swagger resources are served. For e.g. if the api is available at http://example.org/api/v2/api-docs then the base url is http://example.org/api/. Please enter the location manually:
4.启动工程访问swagger2的api接口
http://localhost:8070/v2/api-docs
5.使用swagger-ui提供的默认ui查看接口列表
http://localhost:8070/swagger-ui.htm
6.如果使用Gson需加入配置类及适配器
@Configuration
public class GsonHttpMessageConverterConfig {
@Bean
public GsonHttpMessageConverter gsonHttpMessageConverter() {
GsonHttpMessageConverter converter = new GsonHttpMessageConverter();
converter.setGson(gson());
return converter;
}
private Gson gson() {
final GsonBuilder builder = new GsonBuilder();
builder.registerTypeAdapter(Json.class, new SpringfoxJsonToGsonAdapter());
return builder.create();
}
}
public class SpringfoxJsonToGsonAdapter implements JsonSerializer<Json> {
@Override
public JsonElement serialize(Json json, Type type, JsonSerializationContext context) {
final JsonParser parser = new JsonParser();
return parser.parse(json.value());
}
}
参考资料
https://swagger.io/open-source-integrations/
http://blog.csdn.net/qq_25615395/article/details/70229139
https://springfox.github.io/springfox/
http://springfox.github.io/springfox/docs/current/#springfox-samples
