作为后端开发人员,接口文档肯定是要接触到的,但是swagger原生UI界面不是那么漂亮和清晰,接下来为大家介绍两款swagger增强UI实现
SwaggerBootstrapUI 与 knife4j
springBoot集成SwaggerBootstrapUI
1.导包
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.6</version> </dependency>
2.编写swagger配置类
@Configuration@EnableSwagger2@EnableSwaggerBootstrapUIpublic class SwaggerConfig { @Value("${swagger.enable}") private boolean enableSwagger; @Value("${swagger.serviceUrl}") private String serviceUrl; @Value("${swagger.contact}") private String contact; @Value("${swagger.title}") private String title; @Value("${swagger.version}") private String version; @Value("${swagger.basePackage}") private String basePackage; @Value("${swagger.description}") private String description; @Bean public Docket createRestApi() { ParameterBuilder tokenpar = new ParameterBuilder(); List<Parameter> pars = new ArrayList<Parameter>(); tokenpar.name("AuthToken").description("AuthToken") .modelRef(new ModelRef("string")).parameterType("header") .required(false).build(); //header中的ticket参数非必填,传空也可以 pars.add(tokenpar.build()); //根据每个方法名也知道当前方法在设置什么参数 return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(enableSwagger) .select() .apis(RequestHandlerSelectors.basePackage(basePackage)) .paths(PathSelectors.any()) .build() .globalOperationParameters(pars); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title(title) .description(description) .termsOfServiceUrl(serviceUrl) .contact(contact) .version(version) .build(); }}
上述参数可以直接在代码中写,我是为了后期维护方便将其放在springboot配置文件中配置,yml如下
swagger: enable: true #swagger接口网站开启配置 basePackage: com.hanwin #基础扫描包范围 serviceUrl: http://127.0.0.1:8887/doc.html #服务器接口文档访问地址 contact: liuhhxxxxx.com #联系人邮箱 title: Swagger1.9.6接口文档 #接口文档标题 version: v1.1 #接口文档版本 description: 接口文档查看和接口调试 #接口文档描述
注意: 接口文档端口号需与项目端口号一致
3,在完成了上述配置后,其实已经可以生产文档内容,但是这样的文档主要针对请求本身,而描述主要来源于函数等命名产生,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容。如下所示,我们通过@ApiOperation
注解来给API增加说明、通过@ApiImplicitParam注解来给参数增加说明。例如:
@RestController@RequestMapping("/SysUser")@Api(tags = "系统管理-用户管理【√】",value = "/SysUserController", description = "",position = 1)public class SysUserController { @Autowired(required=false) private SysUserService sysUserService; @PostMapping("/getAllDataList") @ApiOperation(value = "【9】获取列表,不分页【√】", position = 9) public ResultModel<List<SysUserEntity>> getAllDataList(HttpServletRequest request) { return sysUserService.getAllList(request); } @PostMapping("/getDataById") @ApiOperation(value = "获取单个,根据主键id【√】", position = 10) @ApiImplicitParam(name = "id", value = "主键id", required = true, paramType = "query", dataType = "String") public ResultModel<SysUserEntity> getDataById(HttpServletRequest request, String id){ return sysUserService.getById(request, id); } }
实体类也可通过注解进行说明
@ApiModel(value = "用户表")public class SysUserEntity implements Serializable, Cloneable { @ApiModelProperty( value="人员id") private String id; @ApiModelProperty( value="人员姓名") private String name; @ApiModelProperty( value="性别 男/女") private String gender; @ApiModelProperty( value="电子邮箱") private String email; @ApiModelProperty( value="机构id") private String depId; @ApiModelProperty( value="办公电话") private String officePhone; @ApiModelProperty( value="职务") private String duty;}
4.访问接口文档效果如图
5.调试接口如图
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-rFgheprP-1635486969173)(https://mmbiz.qpic.cn/mmbiz_png/RpIVx9Dk1maVU9t9GibFYDLa9iawoc5QmPHdeCGkvzJCbBFZqjYAU08khPJNj2H1pVIrxEjdeBUfZericJKk9hSkw/640?wx_fmt=png)]
6.响应结果效果图
knife4j的使用方法与SwaggerBootstrapUI大致相同,替换坐标即可
<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-boot-starter</artifactId> <!--在引用时请在maven中央仓库搜索最新版本号--> <version>2.0.4</version></dependency>
将swagger配置类中的@EnableSwaggerBootstrapUI注解换成@EnableKnife4j就OK了
效果如图(暗黑系)
最后附上swagger2常用注解
@Api()用于类;表示标识这个类是swagger的资源
@ApiOperation()用于方法;表示一个http请求的操作
@ApiParam()用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等)
@ApiModel()用于类表示对类进行说明,用于参数用实体类接收
@ApiModelProperty()用于方法,字段表示对model属性的说明或者数据操作更改
@ApiIgnore()用于类,方法,方法参数表示这个方法或者类被忽略
@ApiImplicitParam() 用于方法表示单独的请求参数
@ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
具体使用说明举例:
@Api()用于类;表示标识这个类是swagger的资源tags–表示说明value–也是说明,可以使用tags替代但是tags如果有多个值,会生成多个list
@Api(value="用户controller",tags={"用户操作接口"})@RestControllerpublic class UserController {}
@ApiOperation() 用于方法;表示一个http请求的操作value用于方法描述notes用于提示内容tags可以重新分组(视情况而用)@ApiParam() 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等)name–参数名value–参数说明required–是否必填
@Api(value="用户controller",tags={"用户操作接口"})@RestControllerpublic class UserController { @ApiOperation(value="获取用户信息",tags={"获取用户信息copy"},notes="注意问题点") @GetMapping("/getUserInfo") public User getUserInfo(@ApiParam(name="id",value="用户id",required=true) Long id,@ApiParam(name="username",value="用户名") String username) { // userService可忽略,是业务逻辑 User user = userService.getUserInfo(); return user; }}
@ApiModel()用于类 ;表示对类进行说明,用于参数用实体类接收value–表示对象名description–描述都可省略@ApiModelProperty()用于方法,字段;表示对model属性的说明或者数据操作更改value–字段说明name–重写属性名字dataType–重写属性类型required–是否必填example–举例说明hidden–隐藏
@ApiModel(value="user对象",description="用户对象user")public class User implements Serializable{ private static final long serialVersionUID = 1L; @ApiModelProperty(value="用户名",name="username",example="xingguo") private String username; @ApiModelProperty(value="状态",name="state",required=true) private Integer state; private String password; private String nickName; private Integer isDeleted; @ApiModelProperty(value="id数组",hidden=true) private String[] ids; private List<String> idList; //省略get/set} @ApiOperation("更改用户信息") @PostMapping("/updateUserInfo") public int updateUserInfo(@RequestBody @ApiParam(name="用户对象",value="传入json格式",required=true) User user){ int num = userService.updateUserInfo(user); return num; }
@ApiIgnore()用于类或者方法上,可以不被swagger显示在页面上比较简单, 这里不做举例
@ApiImplicitParam() 用于方法表示单独的请求参数@ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParamname–参数mingvalue–参数说明dataType–数据类型paramType–参数类型example–举例说明
@ApiOperation("查询测试") @GetMapping("select") //@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query") @ApiImplicitParams({ @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"), @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")}) public void select(){ }
简单介绍到这… 完