参考自：https://blog.csdn.net/u014231523/article/details/54562695
1. POM引用相关依赖
<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>
2. 创建swagger配置类
package com.xxx.xxx.core.common.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.sf.avcp.core"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("XXX平台API文档")
.description("XXX平台API文档")
.termsOfServiceUrl("http://yourTermsOfService.com")
.version("1.0")
.build();
}
}
启动服务后，这时候可以查看以下地址
swagger会显示已填写的title，description等信息。
${port}为application.properties中设置的端口号(如果不设置，默认为8080)
http://${ip}:${port}/swagger-ui.html#/
3. 在自己的Controller添加相关的注解
- 原来的Controller类上使用的@controller，现在可以使用@RestController代替
- 方法的@ResponseBody可以不用写了，因为版本在4.0.1之后的@RestController的注解接口上已经添加了。
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Controller
@ResponseBody
public @interface RestController {
/**
* The value may indicate a suggestion for a logical component name,
* to be turned into a Spring bean in case of an autodetected component.
* @return the suggested component name, if any
* @since 4.0.1
*/
String value() default "";
}
常用的注解如下：
- @Api()用于类名
- @ApiOperation()用于方法名
- @ApiParam()用于参数说明
- @ApiModel()用于实体类
- @ApiModelProperty用于实体类属性
更加详细的含义可以参考官方说明wiki
这里会把相应包下的所有controller按类进行显示。
我们看下一些例子（请忽略业务逻辑，只看注解）
- Get的例子
@RequestMapping("/hotline")
@RestController
@Api(tags = "热点线路统计分析接口")
public class HotLineController {
@ApiResponses(value = { @ApiResponse(code = 500, message = "系统错误"),
@ApiResponse(code = 200, message = "0 成功,其它为错误") })
@ApiOperation(httpMethod = "GET", value = "获取热度前10条线路")
@RequestMapping(method = RequestMethod.GET, value = "/getTop10Lines")
public SimpleResponse<List<GroundHotLine>> getTop10Lines() {
//逻辑略
}
}
- Post的例子
@RequestMapping("/adas_alarm")
@RestController
@Api(tags = "ADAS告警接口")
public class AdasAlarmController {
@ApiResponses(value = { @ApiResponse(code = 500, message = "系统错误"),
@ApiResponse(code = 200, message = "0 成功,其它为错误") })
@ApiOperation(httpMethod = "POST", value = "查询adas告警统计数据(司机纬度)")
@RequestMapping(method = RequestMethod.POST, value = "/querySummaryByDriver")
public SimpleResponse<Page<AdasAlarmSummaryByDriver>> querySummaryByDriver(
@RequestBody @ApiParam(value = "查询参数", required = true) AdasAlarmDriverCond queryParams) {
//逻辑略
}
}
使用对象作为参数时，可以在对象上添加相应的注解，用户页面显示
PS：这里还用到lombok.Data注解，省略Getter和Setter
- 参数for Post
import lombok.Data;
@Data
public class AdasAlarmDriverCond {
@ApiModelProperty(value = "司机名称")
private String driverName;
@ApiModelProperty(value = "司机工号")
private String driverEmpCode;
// 是否支持分页逻辑 目的用于分页和丰分页的区分
@ApiModelProperty(hidden = true)
private String pageFlag;
}
- 参数for说明required=true（用于Get）
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.util.List;
@ApiModel(description="用户对象user")
public class User {
@ApiModelProperty(value="用户名",name="username")
private String username;
@ApiModelProperty(value="状态",name="state",required=true)
private Integer state;
private String password;
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public Integer getState() {
return state;
}
public void setState(Integer state) {
this.state = state;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
}
如果在字段(如：state)上添加注释
@ApiModelProperty(required=true)
那么在swagger前端上做调用/测试时就是必填（默认是false）
