集成Swagger

发表时间:2017-11-30 11:45:36 浏览量( 21 ) 留言数( 0 )

学习目标:

1、了解Swagger的作用

2、掌握使用spring集成Swagger


学习过程:

    使用Restful接口后,可以让前端工程师和后端工程师更好的分离工作,但是马上也会遇到一个沟通问题,一个接口写完后后端如何通知前端工程师呢,接口也是会经常改变的,如何让前端工程师了解到最新的接口呢?以前可能每一个接口都会出一份文档的,常常会遇到接口更新了,导致和文档对应不上的问题。这时候我们可以使用Swagger帮我们解决这个问题,文档可以不写了,接口的调试也会更简单。

一、搭建环境

1、导入依赖包

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.6.1</version>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.6.1</version>
		</dependency>

2、添加配置类

@EnableWebMvc
@EnableSwagger2
@Configuration
public class SwaggerConfig {

    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()) 
          .select()                                  
          .apis(RequestHandlerSelectors.basePackage("com.javadayup.ump.control"))    //需要扫描的control          
          .paths(PathSelectors.any())                          
          .build();                                           
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("javadayup接口 v1.0")  
                .description("javadayup接口测试") 
                .version("1.0")
                .build();
    }
}

3、配置资源文件路径和扫描路径

	<context:component-scan base-package="com.javadayup.ump.control,springfox">
	<!-- swagger -->
	<mvc:resources mapping="swagger-ui.html" location="classpath:/META-INF/resources/"></mvc:resources>
	<mvc:resources mapping="/webjars/**"
		location="classpath:/META-INF/resources/webjars/"></mvc:resources>


<!-- 
    如果有说明登陆拦截记得要不要拦截
	<mvc:interceptors>
		<mvc:interceptor>
			<mvc:mapping path="/**" />
			<mvc:exclude-mapping path="/swagger*/**"></mvc:exclude-mapping>
			<mvc:exclude-mapping path="/v2/**"></mvc:exclude-mapping>
			<mvc:exclude-mapping path="/webjars/**"></mvc:exclude-mapping>
		</mvc:interceptor>
	</mvc:interceptors> -->


二、编写测试类

1、在model中添加说明注解

@ApiModel(description="员工信息")
public class UmpEmployee implements Serializable {
	
	@ApiModelProperty(name="employeeId",value="id")
    private Long employeeId;

	@ApiModelProperty(notes="姓名",value="姓名value")
    private String employeeName;

	@ApiModelProperty(name="状态",value="1:在职,2:离职")
    private Integer state;

2、在control层中添加api说明注解

@RestController
@RequestMapping("/")
public class UmpEmployeeControl {
	private final static Logger logger = LoggerFactory.getLogger(UmpEmployeeControl.class);

	@Autowired
	private UmpEmployeeApi umpEmployeeApi;

	/**
	 * 
	 * 
	 * @return
	 */
	@RequestMapping(value = "/addEmployee", method = RequestMethod.POST)
	@ApiOperation(value = "添加新员工")
	@ApiImplicitParam(name = "employee", value = "员工")
	public String addEmployee(UmpEmployee employee) {

		int result = umpEmployeeApi.addEmployee(employee);

		return result + "";
	}

	@RequestMapping(value = "listEmployee", method = RequestMethod.POST, produces = "application/json;charset=utf-8")
	@ApiOperation(value = "分页查询员工")
	@ApiImplicitParam(name = "employeeSearch", value = "员工")
	public Map<String, Object> listEmployee(EmployeeSearch employeeSearch) {

		Map<String, Object> result = new HashMap<String, Object>();

		result = umpEmployeeApi.queryEmployee(employeeSearch);

		return result;
	}

}

三、效果

我们可以打开并测试了。后面的swagger-ui.html是前面配置的路径

http://localhost:9090/niuyou-ump-web/swagger-ui.html

attcontent/6e1f07a0-97cc-4811-83fd-a260d07b3706.png

测试

attcontent/a2e12d5a-9aa9-4259-aa4d-4e97496346fe.png

attcontent/92fc60cb-e6b4-472a-8552-3b5961b0d265.png

四、其他常用注解

一、swagger常用注解

1、与模型相关的注解

两个注解:

@ApiModel:用在模型类上,对模型类做注释;

@ApiModelProperty:用在属性上,对属性做注释


2、与接口相关的注解

六个注解:

@Api:用在controller上,对controller进行注释;

@ApiOperation:用在API方法上,对该API做注释,说明API的作用;

@ApiImplicitParams:用来包含API的一组参数注解,可以简单的理解为参数注解的集合声明;

@ApiImplicitParam:用在@ApiImplicitParams注解中,也可以单独使用,说明一个请求参数的各个方面,该注解包含的常用选项有:

paramType:参数所放置的地方,包含query、header、path、body以及form,最常用的是前四个。

name:参数名;

dataType:参数类型,可以是基础数据类型,也可以是一个class;

required:参数是否必须传;

value:参数的注释,说明参数的意义;

defaultValue:参数的默认值;

@ApiResponses:通常用来包含接口的一组响应注解,可以简单的理解为响应注解的集合声明;

@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息

code:即httpCode,例如400 

message:信息,例如"请求参数没填好"