一,swagger简介
swagger是一个在线接口说明文档,在代码中通过注解的方式将说明问题集成到项目,代码发生修改,说明文档同步修改,前后台联调可以快速同步数据。
二,应用设置swagger
以openfeign项目为例
1、引入依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、编写配置类
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;
/**
* @author szsw
* @date 2023/3/1 18:12:17
*/
@Configuration
public class SwaggerConfig {
@Bean
public Docket docket() {
/*采用swagger2版本*/
return new Docket(DocumentationType.SWAGGER_2)
/*生成api相关信息*/
.apiInfo(createApiInfo())
/*返回一个apiSelectorBuilder对象,用来控制接口生成在线文档*/
.select()
/*扫描某个包下的接口 根据实际情况进行改变 swagger会生成文档下类相关的文档描述*/
.apis(RequestHandlerSelectors.basePackage("org.jsoft.demo.controller"))
/*生成所有的api*/
.paths(PathSelectors.any())
.build();
}
/**
* 创建api相关信息
*
* @return ApiInfo
*/
private ApiInfo createApiInfo() {
return new ApiInfoBuilder()
/*自定义title*/
.title("swagger demo")
/*描述*/
.description("swagger示例")
/*定义服务域名*/
.termsOfServiceUrl("")
/*自定义版本号*/
.version("0.0.1")
.build();
}
}
3、开启Swagger
在启动类中添加:
@EnableSwagger2
4、编写示例
当 .apis(RequestHandlerSelectors.basePackage("org.jsoft.demo.controller"))下的controller中用元素涉及对象使用,在相应对象上也要加swagger相关注解
1、实体类
package org.jsoft.demo.dto;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.util.Date;
@Data
@ApiModel
public class UserUpdateDto {
@ApiModelProperty(value = "主键", required = true, example = "asdfa54s56d")
private String id;
@ApiModelProperty(value = "名字", required = true, example = "张三")
private String name;
@ApiModelProperty(value = "密码", required = true, example = "123456")
private String password;
@ApiModelProperty(value = "年龄", required = true, example = "20")
private Integer age;
@ApiModelProperty(value = "生日", required = true, example = "1998-07-07")
private Date birthday;
@ApiModelProperty(value = "分数", example = "100.5")
private Double score;
}
/*
value 描述
required 必填项
example 举例
*/
package org.jsoft.demo.dto;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.util.Date;
@Data
@ApiModel
public class UserAddDto {
@ApiModelProperty(value = "名字", required = true, example = "张三")
private String name;
@ApiModelProperty(value = "密码", required = true, example = "123456")
private String password;
@ApiModelProperty(value = "年龄", required = true, example = "20")
private Integer age;
@ApiModelProperty(value = "生日", required = true, example = "1998-07-07")
private Date birthday;
@ApiModelProperty(value = "分数", example = "100.5")
private Double score;
}
2、Controller
package org.jsoft.demo.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.jsoft.demo.dto.UserAddDto;
import org.jsoft.demo.dto.UserUpdateDto;
import org.jsoft.demo.utils.Result;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;
import java.util.Map;
@Api(tags = "用户")
@RestController
@RequestMapping("/user")
public class UserController {
@PostMapping
@ApiOperation("用户新增")
public Result add(@RequestBody UserAddDto dto) {
return Result.ok();
}
@DeleteMapping("/{id}")
@ApiOperation("用户删除")
@ApiImplicitParams({
@ApiImplicitParam(value = "删除的用户主键", name = "id", paramType = "path")
})
//使用了基本数据类型要用 @ApiImplicitParams进行注解解释
public Result delete(@PathVariable String id) {
return Result.ok();
}
@PutMapping
@ApiOperation("用户修改")
public Result update(@RequestBody UserUpdateDto dto) {
return Result.ok();
}
@GetMapping("/{id}")
@ApiOperation("用户详情")
@ApiImplicitParams({
@ApiImplicitParam(value = "用户主键", paramType = "path") //path是指地址传参。
})
public Result info(@PathVariable String id) {
return Result.ok();
}
@GetMapping
@ApiOperation("用户查询")
@ApiImplicitParams({
@ApiImplicitParam(value = "姓名", name = "name", paramType = "query"),
@ApiImplicitParam(value = "年龄", name = "age", paramType = "query"),
@ApiImplicitParam(value = "分数", name = "score", paramType = "query") // get地址栏传参
})
public Result query(@ApiIgnore @RequestParam Map<String, String> params) {
return Result.ok();
}
}
//query和path方式
//http://127.0.0.1/user/del?mal
//query是mal在?后,path在?前
3、访问地址
http:localhost:100/swagger-ui.html