spring-boot学习：十八、spring-boot集成swagger

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

spring-boot学习：十八、spring-boot集成swagger

猜你喜欢