两款Swagger UI界面

作为后端开发人员,接口文档肯定是要接触到的,但是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
@EnableSwaggerBootstrapUI
public 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.调试接口如图

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={"用户操作接口"})
@RestController
public class UserController {

}

@ApiOperation() 用于方法；表示一个http请求的操作value用于方法描述notes用于提示内容tags可以重新分组（视情况而用）@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）name–参数名value–参数说明required–是否必填

@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public 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(){

  }

简单介绍到这.. 完