接口文档的开发之JAVA项目的骚操作

关于JAVA开发中的接口文档，目前已有不少的工具可以支持。

但是对于后端开发工程师，如果只需关注自己的controller就可以实现接口文档，该是多幸福的事啊！接下来，你可以认为我就是给你带来这个福音的亚当。

在Maven项目中，先引用如下POM节点

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
</dependency>

新建一个配置类，内容如下

@Configuration
public class AbstractSwagger2Config {
  @Bean
    public Docket adminApiDoc(){
        return new Docket(DocumentationType.OAS_30)
                .groupName("管理端接口文档")
                .pathMapping("/")
                // 定义是否开启swagger，false为关闭，可以通过变量控制，线上关闭
                .enable(true)
                //配置api文档元信息
                .apiInfo(apiInfo())
                // 选择哪些接口作为swagger的doc发布
                .select()
                .apis(RequestHandlerSelectors.basePackage("vip.clbgw"))
                //正则匹配请求路径，并分配至当前分组
                .paths(PathSelectors.ant("/admin/**"))
                .build();
    }
  
  @Bean
    public Docket webApiDoc(){
        return new Docket(DocumentationType.OAS_30)
                .groupName("用户端接口文档")
                .pathMapping("/")
                // 定义是否开启swagger，false为关闭，可以通过变量控制，线上关闭
                .enable(true)
                //配置api文档元信息
                .apiInfo(apiInfo())
                // 选择哪些接口作为swagger的doc发布
                .select()
                .apis(RequestHandlerSelectors.basePackage("vip.clbgw"))
                //正则匹配请求路径，并分配至当前分组
                .paths(PathSelectors.ant("/api/**"))
                //正则匹配请求路径，并分配至当前分组，当前所有接口
                .paths(PathSelectors.any())
                .build()
                //新版swagger3.0配置
                .globalRequestParameters(getGlobalRequestParameters())
                .globalResponses(HttpMethod.GET, getGlobalResponseMessage())
                .globalResponses(HttpMethod.POST, getGlobalResponseMessage());

    }
  
  /**
     * 生成全局通用参数, 支持配置多个响应参数
     * @return
     */
    private List<RequestParameter> getGlobalRequestParameters() {
        List<RequestParameter> parameters = new ArrayList<>();
        parameters.add(new RequestParameterBuilder()
                .name("token")
                .description("登录令牌")
                .in(ParameterType.HEADER)
                .query(q -> q.model(m -> m.scalarModel(ScalarType.STRING)))
                .required(false)
                .build());
        return parameters;
    }


/**
     * 生成通用响应信息
     * @return
     */
    private List<Response> getGlobalResponseMessage() {
        List<Response> responseList = new ArrayList<>();
        responseList.add(new ResponseBuilder().code("4xx").description("请求错误，根据code和msg检查").build());
        return responseList;
    }
}

之后的重头戏就在controller中了（灵魂如下）：

@Api( tags = "国密3算法控制器")
@RestController
public class Sm3Controller {
    /**
     * SM3签名
     *
     * @param src 源字符串
     * @return 响应对象
     */
    @ApiOperation("SM3签名")
    @GetMapping("/sm3/sign")
    public R sign(String src) {
        Sm3Util sm3Util = new Sm3Util();
        byte[] signArr = sm3Util.sign(src.getBytes());
        return ResponseUtil.ok(Util.byteToHex(signArr));
    }
    
    /**
     * SM3验签
     *
     * @param src     源字符串
     * @param signStr 签名字符串
     * @return 响应对象
     */
    @ApiOperation("SM3验签")
    @GetMapping("/sm3/verify")
    public R verify(String src, String signStr) {
        Sm3Util sm3Util = new Sm3Util();
        boolean result = sm3Util.verify(src.getBytes(), Util.hexToByte(signStr));
        return ResponseUtil.ok(result);
    }
}

重要的就是如上的@Api( tags = "国密3算法控制器") 和

@ApiOperation("SM3验签") 这两个注解。

经过如上的代码炮制，你就可以访问swagger（丝袜哥）的特有页面了。

http://localhost:8080/swagger-ui/index.html#/

好了，以上就是接口文档丝袜哥的重点和使用内容了，如果你也喜欢编程技术的话，关注我就可以第一时间收到我的文章分享哦！欢迎一键三连。