SSM整合swagger2（jar包项目，非maven）

SSM整合swagger2（jar包项目，非maven）

1.为什么使用Swagger2

当下很多公司都采取前后端分离的开发模式，前端和后端的工作由不同的工程师完成。在这种开发模式下，维持一份及时更新且完整的 Rest API 文档将会极大的提高我们的工作效率。传统意义上的文档都是后端开发人员手动编写的，相信大家也都知道这种方式很难保证文档的及时性，这种文档久而久之也就会失去其参考意义，反而还会加大我们的沟通成本。而 Swagger 给我们提供了一个全新的维护 API 文档的方式，动态生成Api接口文档，降低沟通成本，促进项目高效开发。

优点：

代码变，文档变。很好的保证了文档的时效性。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档。

2.jar包依赖

guava-20.0.jar --重点
jackson-annotations-2.8.6.jar
jackson-core-2.8.6.jar
jackson-databind-2.8.6.jar
springfox-core-2.9.2.jar
springfox-schema-2.9.2.jar
springfox-spi-2.9.2.jar
springfox-spring-web-2.9.2.jar
springfox-swagger-common-2.9.2.jar
springfox-swagger-ui-2.9.2.jar
springfox-swagger2-2.9.2.jar
swagger-annotations-1.5.21.jar
swagger-models-1.5.21.jar

如果没有guava-20.0.jar会出现 无法访问com.google.common.base.Predicate 找不到com.google.common.base.Predicate的类文件

3.swagger配置

swagger配置类

import java.util.ArrayList;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
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;
/**
 * Swagger接口文档生成配置类
 * @author wwh
 *
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig{

	@Bean
	public Docket createRestApi(){
		return new Docket(DocumentationType.SWAGGER_2)
			.apiInfo(apiInfo())
	        .enable(true)//是否开启开发接口文档
	        .select()
	        //.apis(RequestHandlerSelectors.any())为任何接口生成API文档，这种方式不必在接口方法上加任何注解，方便的同时也会因为没有添加任何注解所以生成的API文档也没有注释，可读性不高。
	        //.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//为有@Api注解的Controller生成API文档
	        //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//为有@ApiOperation注解的方法生成API文档
            .apis(RequestHandlerSelectors.basePackage("com.hthealthcare.other.controller"))//为当前配置的包下controller生成API文档
            .build();
	}
	
	/*private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger演示接口文档")
                .description("swagger演示项目接口,请认证填写接口文档说明")
                .version("1.0.0")
                .termsOfServiceUrl("")
                .contact(new Contact("张三", "url", "邮箱"))
                .license("swagger演示 1.0.0")
                .licenseUrl("")
                .build();
    }*/
	private ApiInfo apiInfo(){
        //设置联系方式
	       Contact contact = new Contact("张三","url", "邮箱");
	       return  new ApiInfo(
	         "swagger演示接口文档",
	         "swagger演示项目接口,请认证填写接口文档说明",
	         "1.0.0",
	         "",
	          contact,
	         "swagger演示 1.0.0",
	         "",
	          new ArrayList<>()
	       );
	    }

}

swagger在springmvc.xml中的配置

<!-- 配置扫描包,开启Spring的IOC注解功能 -->
<context:component-scan base-package="com.test.controller"/>
<!-- 静态资源放行 -->
<mvc:default-servlet-handler />
<!-- 添加Swagger配置 -->
<!-- 将SwaggerConfig配置类注入 -->
<bean id="swaggerConfig" class="com.test.config.SwaggerConfig"/>
<!-- 配置swagger资源不被拦截 -->
<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>

web.xml配置

<!-- SpringMVC配置 -->
	<servlet>
		<servlet-name>dispatcherServlet</servlet-name>
		<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
		<init-param>
			<param-name>contextConfigLocation</param-name>
			<param-value>classpath:spring-mvc.xml</param-value>
		</init-param>
		<load-on-startup>1</load-on-startup>
	</servlet>
	<servlet-mapping>
		<servlet-name>dispatcherServlet</servlet-name>
		<!-- <url-pattern>*.do</url-pattern> -->
		<url-pattern>/</url-pattern><!-- 为使用swagger -->
	</servlet-mapping>
	<!-- End SpringMVC配置 -->

如果以前用的是*.do，需要改为 / ；解决 *.do，可以通过<mvc:interceptors></mvc:interceptors>进行拦截

4.代码案例

@Api(tags = "登录-登录相关接口")
@RestController
@RequestMapping("/other/login")
public class LoginController {

	@Autowired
	private External_UserService external_UserService;
	
	@PostMapping(value = "/login.do")
	@ApiOperation("登录")
	@ApiImplicitParams({
        @ApiImplicitParam(name = "username",value = "账号",type = "String"),
        @ApiImplicitParam(name = "password",value = "密码",type = "String")
	})
    public Result login(@RequestParam String username,@RequestParam String password,HttpSession session){
		User user = external_UserService.findUserByUsername(username);
		
		if(null != user){
			if(user.getPassword().equals(password)){
				//放入session
				session.setAttribute(Constants.USER_SESSION, user);
				return ResultFactory.buildSuccessResult(user);
			}else{
				return ResultFactory.buildFailResult("密码错误!");
			}
		}else{
			return ResultFactory.buildFailResult("账号错误!");
		}
    }
	
}

5.swagger常用注解

@Api： controller接口类说明

参数：tags="说明该类的作用"

@ApiOperation：controller接口类中方法的说明

参数 value="说明方法的作用"
    notes="方法的备注说明"

@ApiImplicitParam：一个请求参数
@ApiImplicitParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”）

@ApiImplicitParams：多个请求参数
@ApiImplicitParams({
            @ApiImplicitParam(name = "sign",value = "单位类型标识(sign:1为学校;2为医院,3为房地产,4为互联网)",type = "Integer",required = true),
            @ApiImplicitParam(name = "projectId",value = "项目id",type = "Integer",required = true),
            @ApiImplicitParam(name = "hospitalId",value = "医院(中心)id",type = "Integer"),
            @ApiImplicitParam(name = "departmentId",value = "科室id",type = "Integer")
            
    })

@ApiProperty：用对象接实体收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：一个请求参数
@ApiImplicitParams： 多个请求参数

6.访问测试

http://ip:端口号/项目名称/swagger-ui.html