SpringMvc 集成swagger2

swagger：restful管理项目API工具

1、pom.xml增加依赖包

 <!-- swagger-mvc -->  
<dependency>  
            <groupId>io.springfox</groupId>  
            <artifactId>springfox-swagger2</artifactId>  
            <version>2.4.0</version>  
        </dependency>  
        <dependency>  
            <groupId>io.springfox</groupId>  
            <artifactId>springfox-swagger-ui</artifactId>  
            <version>2.4.0</version>  
        </dependency>  
        <!-- swagger-mvc -->  
<!-- json -->  
        <dependency>  
            <groupId>com.fasterxml.jackson.core</groupId>  
            <artifactId>jackson-core</artifactId>  
            <version>2.6.5</version>  
        </dependency>  
        <dependency>  
            <groupId>com.fasterxml.jackson.core</groupId>  
            <artifactId>jackson-databind</artifactId>  
            <version>2.6.5</version>  
        </dependency>  
        <dependency>  
            <groupId>com.fasterxml.jackson.core</groupId>  
            <artifactId>jackson-annotations</artifactId>  
            <version>2.6.5</version>  
        </dependency>  

2、在spring-mvc.xml中声明swagger配置bean

<bean class="springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration" id="swagger2Config"/>  



//有人也说配置不生效时候需要在springmvc中声明
//<bean class="com.esmall.seller.context.RestApiConfig"></bean>

3.在spring-mvc.xml中配置资源文件

<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>  
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>  

4.配置控制器

<context:component-scan base-package="com.zhcs.controller" />

5.添加文档内容

在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。如下所示，我们通过@ApiOperation注解来给API增加说明、通过@ApiImplicitParams、@ApiImplicitParam注解来给参数增加说明。

@Resource
	private UserService userService;
	
	@RequestMapping("/showUser")
	@ApiOperation(value = "获取用户详细信息", notes = "根据url的id来获取用户详细信息")  
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
	public String toIndex(HttpServletRequest request,Model model) {
		LogUtil.info("UserController showUser");
		int id = Integer.parseInt(request.getParameter("id"));  
        User user = userService.selectByPrimaryKey(id);  
        model.addAttribute("str", user.getUserName());  
        return "showUser";  
	}
	
	@RequestMapping("/showAllUser")
	@ApiOperation(value = "获取用户列表", notes = "")  
	public String showAllUser(HttpServletRequest request, Model model) {
		System.out.println("UserController showAllUser");
		List<User> user = userService.getUserByAll();  
		System.out.println(user.size());
		System.out.println(JSON.toJSONString(user));
		model.addAttribute("str", StringUtil.valueOf(JSON.toJSONString(user), "無數據"));
		return "showUser";  
	}

6.添加config

import org.springframework.context.annotation.Bean;  
import org.springframework.context.annotation.ComponentScan;  
import org.springframework.context.annotation.Configuration;  
import org.springframework.web.servlet.config.annotation.EnableWebMvc;  
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;  
  
  

import springfox.documentation.builders.ApiInfoBuilder;  
import springfox.documentation.builders.PathSelectors;  
import springfox.documentation.builders.RequestHandlerSelectors;  
import springfox.documentation.service.ApiInfo;  
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;  
import springfox.documentation.spring.web.plugins.Docket;  
import springfox.documentation.swagger2.annotations.EnableSwagger2;  

@EnableWebMvc  
@EnableSwagger2  
@ComponentScan(basePackages = {"com.zhcs.controller"})  
@Configuration  
public class RestApiConfig extends WebMvcConfigurationSupport{  
  
    @Bean  
    public Docket createRestApi() {  
        return new Docket(DocumentationType.SWAGGER_2)  
                .apiInfo(apiInfo())  
                .select()  
                .apis(RequestHandlerSelectors.basePackage("com.zhcs.controller"))  
                .paths(PathSelectors.any())  
                .build();  
    }  
  
    private ApiInfo apiInfo() {  
        return new ApiInfoBuilder()  
                .title("SmartCityServiceAPIDocument")  
                .termsOfServiceUrl("http://xzrwy.com")  
                .contact(new Contact("Alter", "http://alterempty.cn", "404221903@qq.com"))  
                .version("1.1")  
                .build();  
    }  
}  

完成上述代码添加上，启动程序，访问：http://localhost:8080/swagger-ui.html
。就能看到前文所展示的RESTful API的页面。我们可以再点开具体的API请求，以POST类型的/users请求为例，可找到上述代码中我们配置的Notes信息以及参数user的描述信息，如下图所示。

 

转载于:https://my.oschina.net/alters/blog/843786