一、上代碼
0.pom.xml
<!-- swgger 檢測spring的web請求信息猖败，生成檢測結(jié)果（json格式）速缆。 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId> <!-- 檢測spring的web請求信息，生成檢測結(jié)果（json格式）恩闻。 -->
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId> <!-- 根據(jù)springfox-swagger2生成的數(shù)據(jù)艺糜，生成可視化的友好頁面。 -->
<version>2.9.2</version>
</dependency>
1.Swagger2Conf
@Configuration
@EnableSwagger2
public class Swagger2Conf {
@Bean
public Docket getUserDocket(){
ParameterBuilder parameterBuilder = new ParameterBuilder();
List<Parameter> parameters = new ArrayList<Parameter>();
parameterBuilder.name("X-Token").description("認(rèn)證token") //Header里添加X-Token參數(shù)用于認(rèn)證
.modelRef(new ModelRef("string")).parameterType("header").required(false).build();
parameters.add(parameterBuilder.build());
ApiInfo apiInfo=new ApiInfoBuilder()
.title("yx-server系統(tǒng)")//api標(biāo)題
.description("yx-server api 接口文檔")//api描述
.version("1.0.0")//版本號
.build();
return new Docket(DocumentationType.SWAGGER_2)//文檔類型（swagger2）
.apiInfo(apiInfo)//設(shè)置包含在json ResourceListing響應(yīng)中的api元信息
.select()//啟動用于api選擇的構(gòu)建器
.apis(RequestHandlerSelectors.basePackage("com.yx.controller"))//掃描接口的包
.paths(PathSelectors.any())//路徑過濾器（掃描所有路徑）
.build().globalOperationParameters(parameters);
}
}
2.Controller注解示例
@RestController
@RequestMapping("/user")
@Api("用戶管理")
public class UserController {
@Resource
UserServicesImpl userServices;
@ApiOperation("登錄")
@RequestMapping(value = "/login", method = RequestMethod.POST)
public Object login(HttpServletResponse response,
@RequestParam(value = "username", required = true) String userName,
@RequestParam(value = "password", required = true) String password) {
//用戶認(rèn)證信息
Subject subject = SecurityUtils.getSubject();
UsernamePasswordToken usernamePasswordToken = new UsernamePasswordToken(userName, password);
try {
//進行驗證判呕，這里可以捕獲異常倦踢，然后返回對應(yīng)信息
subject.login(usernamePasswordToken);
return ApiResult.success(subject.getSession().getId()); //將token返回給前端
} catch (UnknownAccountException e) {
return ApiResult.failure(ResponseCode.ACCOUNT_NOT_EXIST);
} catch (AuthenticationException e) {
return ApiResult.failure(ResponseCode.ACCOUNT_ERROR);
}
}
}
3.POJO注解示例
@Data
@ApiModel("用戶")
public class User {
@ApiModelProperty("用戶名")
private String username;
@ApiModelProperty("密碼")
@JsonProperty(access = JsonProperty.Access.WRITE_ONLY) //表示 Restful接口返回給前臺時不包含該字段
private String password;
@ApiModelProperty("年齡")
private Integer age;
@ApiModelProperty("生日")
@JsonFormat(pattern = "yyyy-MM-dd hh:mm:ss a", locale = "zh", timezone = "GTM+8")
private Date birthday;
@ApiModelProperty("描述")
private String des;
}
二、訪問swagger
image.png
三侠草、 常用注解說明
swagger 通過注解接口生成文檔辱挥，包括接口名，請求方法边涕，參數(shù)晤碘，返回信息等。
@Api: 修飾整個類功蜓，用于controller類上
@ApiOperation: 描述一個接口园爷，用戶controller方法上
@ApiParam: 單個參數(shù)描述
@ApiModel: 用來對象接收參數(shù),即返回對象
@ApiModelProperty: 對象接收參數(shù)時，描述對象的字段
@ApiResponse: Http響應(yīng)其中的描述式撼，在ApiResonse中
@ApiResponses: Http響應(yīng)所有的描述童社，用在
@ApiIgnore: 忽略這個API
@ApiError: 發(fā)生錯誤的返回信息
@ApiImplicitParam: 一個請求參數(shù)
@ApiImplicitParam: 多個請求參數(shù)
更多使用說明，參考 Swagger 使用手冊著隆。
