作为后端开发人员,接口文档肯定是要接触到的,但是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(){  }

简单介绍到这… 完