作为后端开发人员,接口文档肯定是要接触到的,但是swagger原生UI界面不是那么漂亮和清晰,接下来为大家介绍两款swagger增强UI实现
SwaggerBootstrapUI 与 knife4j
springBoot集成SwaggerBootstrapUI
1.导包
io.springfox springfox-swagger22.9.2 com.github.xiaoymin swagger-bootstrap-ui1.9.6
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 pars = new ArrayList(); 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> 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 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大致相同,替换坐标即可
com.github.xiaoymin knife4j-spring-boot-starter2.0.4
将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 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(){ }
简单介绍到这… 完
