swagger通过spring注解自动生成接口文档,可通过swagger-ui展示
- pom.xml
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- Application.java启用swagger2,并注册swagger信息
@SpringBootApplication
@PropertySource(value= {"classpath:database.properties"})
@ServletComponentScan(basePackages = {"com.kevin"})
@MapperScan("com.kevin.dao")
@EnableSwagger2
public class Application extends SpringBootServletInitializer{
@Bean
public Docket petApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo())
.pathMapping("/");
}
// 文档描述信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("spring-boot2 RESTful APIs")
.description("一时快一时爽,一直快一直爽")
.contact(new Contact("Kevin Yu", "https://www.baidu.com", "[email protected]"))
.version("1.0.0")
.build();
}
}
- HelloController.java
package com.kevin.controller;
import java.util.concurrent.atomic.AtomicLong;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import com.kevin.dao.model.Greeting;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
@Api(tags="Hello相关接口")
@RestController
public class HelloController {
private static final String template = "Hello, %s!";
private final AtomicLong counter = new AtomicLong();
@ApiOperation(value="say hello", notes="浅谈一下")
@RequestMapping(value="/hello", method= {RequestMethod.GET})
public Greeting hello(@RequestParam(value="name", defaultValue="World")String name){
return new Greeting(counter.incrementAndGet(), String.format(template, name));
}
public Greeting hello2(@RequestParam(value="name", defaultValue="World")String name){
return new Greeting(counter.incrementAndGet(), String.format(template, name));
}
}
注:swagger会根据@RequestMapping、@RequestParam等spring注解来生成文档
-
查看生成的文档http://127.0.0.1:8081/swagger-ui.html
-
遇到的异常
1)无法正常显示UI
后台日志:
2019-05-27 17:49:32,507 DEBUG [springfox.documentation.spring.web.PropertySourcedRequestMappingHandlerMapping] - looking up handler for path: /swagger-ui.html
2019-05-27 17:49:33,416 DEBUG [springfox.documentation.spring.web.PropertySourcedRequestMappingHandlerMapping] - looking up handler for path: /swagger-resources/configuration/ui
2019-05-27 17:49:33,719 WARN [org.springframework.web.servlet.mvc.support.DefaultHandlerExceptionResolver] - Resolved [org.springframework.web.HttpMediaTypeNotAcceptableException: Could not find acceptable representation]
2019-05-27 17:49:33,732 DEBUG [springfox.documentation.spring.web.PropertySourcedRequestMappingHandlerMapping] - looking up handler for path: /error
错误描述:前端请求/swagger-resources/configuration/ui返回406错误,也就是消息头无法接收(Not acceptable),结合后台Could not find acceptable representation的提示,定位到请求返回的格式错误
原因:启动类中配置MVC内容的处理策略,当请求没有后缀时默认是html格式,而/swagger-resources/configuration/ui实际返回的是json,导致解析错误
@Bean
public WebMvcConfigurer webConfg() {
return new WebMvcConfigurer() {
public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
configurer.favorPathExtension(false).favorParameter(false).ignoreAcceptHeader(true).useRegisteredExtensionsOnly(false)
.defaultContentType(MediaType.TEXT_HTML).mediaType("html", MediaType.TEXT_HTML).mediaType("json", MediaType.APPLICATION_JSON);
}
};
}
解决方案:将默认格式改为json即可,defaultContentType(MediaType.APPLICATION_JSON);
2) /csrf返回404
2.9.2才有,可更换版本
参考:
https://github.com/springfox/springfox/issues/2603
https://github.com/springfox/springfox/pull/2434
http://springfox.github.io/springfox/docs/current/#springfox-spring-mvc-and-spring-boot
扫描二维码关注公众号,回复:
11584899 查看本文章