Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试 的Web服务框架
1、pom.xml增加依赖
Spring项目和SpringBoot项目相同
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
2、新建Swagger的配置文件类 SwaggerConfig.java
2.1 Spring项目文件
Spring项目：
需再修改注解 为 @Configuration、@EnableSwagger2
并继承 extends WebMvcConfigurationSupport
createRestApi() 方法需加注解 @Bean
@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.jaden.***"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("Spring 整合 Swagger2 实例")
.description("Spring 整合 Swagger2")
.termsOfServiceUrl("http://127.0.0.1:8080/xxx_spring")
.version("1.0")
.build();
}
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
2.2 SpringBoot项目文件
@Configurable
public class SwaggerConfig
{
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.jaden.xxx"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("SpringBoot 整合 Swagger2 实例")
.description("SpringBoot 整合 Swagger2")
.termsOfServiceUrl("http://127.0.0.1:8080/xxx_springboot")
.version("1.0")
.build();
}
}
3、SpringBoot项目 修改SpringBoot启动类 增加注解 @EnableSwagger2
SpringBoot项目独有设置
@SpringBootApplication
@EnableSwagger2
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
3、Spring项目 修改springMVC配置文件
Spring+SpringMVC项目独有设置
<context:component-scan base-package="com.jaden.*.controller,com.jaden.*.config" use-default-filters="false" >
<context:include-filter type="annotation"
expression="org.springframework.stereotype.Controller"/>
<context:include-filter type="annotation"
expression="org.springframework.web.bind.annotation.ControllerAdvice"/>
<context:include-filter type="annotation"
expression="org.springframework.context.annotation.Configuration"/>
</context:component-scan>
4、使用 controller、model……上加注解
controller的描述
Controller类
@Api(value = "分类服务API",tags = "分类服务控制器")
value:如果controller类名为UserController，那么此处该名称叫User-API。
description：接口详细描述，建议不要超过25个字。
Controller类中方法
@ApiOperation(value = “获取用户详细信息”, notes = “根据url的id来获取用户详细信息，返回User类型用户信息的实体”)
对该方法的描述
value:接口操作简介，建议不超过15个字。
notes：1，输出结果代表的意义，2实现的功能。若输出结果为基本类型（类似：int,string）需要指名是什么类型，如果有异常信息，需要指明异常信息的类型。
@ApiImplicitParam(name = “id”, value = “用户ID”, required = true, dataType = “String”)
对参数的描述，如果多个参数需要用@ApiImplicitParams对其进行包裹
name:跟方法名中的参数保持一致。
value：对参数的简单描述，说明该参数的意义。
required:该参数是否必填写。
dataType:入参的类型，可以为类名，也可以为基本类型（String，int，Boolean），加包名，如果都不是则不翻译
paramType：如果在路径中提取参数用path，比如:在／A／{XXX}路径中得到XXX的值，候选址参数query, body,header。
model的描述
@ApiModelProperty(value = “用户姓名”,required = true)
private String name
对字段的描述
value：实体类中字段的描述以及可选的取值。例如sex表示用户性别1:男，0:女
required：该字段是否必填，不清楚情况下，建议不要填写，或者required=false
5、访问
http://127.0.0.1:8080/xxx_springboot/
浏览该地址，访问主页面：http://127.0.0.1:8080/xxx_springboot/swagger-ui.html
浏览该地址，访问sagger专有JsonAPI： http://127.0.0.1:8080/xxx_springboot/v2/api-docs
6、Swagger try it out！功能
