Springfox (Swagger) - ApiOperation 注解中的 position 方法无效的拓展解决方案

写在前面

未经允许不得转载!

如果你有现在使用 Springfox 的经历的话，可能就有对 api 进行分组以及排序等需求，而Springfox(应当说是Swagger更确切)默认是根据自然排序对 api 进行排序的，比如："/aaa1"会排在"/aaa2"前面，会排在"/bbb1"前面。

当需要自定义排序规则时怎么办？

• 那就是使用ApiOperation注解的position方法，但是很不幸的是该方法已经标记为过时了，现在保留这个方法只是为了兼容之前的版本，且高版本的已经一移除该功能了（包括后端和前端UI）。

那有其他办法实现自定义排序吗？

• 自己花时间找文档及api看看有没有类似功能
• 按照我的配置方式实现临时用的拓展解决方案（当然只是临时的 毕竟position已经过时了，之后的版本可能就移除了）

相关链接

• Springfox Issues: position of @ApiOperation is not recognized #610
• Springfox Issues: Custom sorting/position is not honored for V2 #732
• 临时拓展解决方案的实现步骤-网速不好的就看文章下面的内容

临时用的拓展解决方案

第1步：在需要的位置添加 position

/*
 *  Copyright 2019 the original author or authors.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *         http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author Yahuan Jin
 * @since 2019.08.24
 */
@Api(tags = "test", description = "test")
@RequestMapping("test/apiOperation")
@RestController
public class ApiOperationTestController {
   
    @ApiOperation(value = "Test position 2", tags = {
   "position-test"}, position = 2)
    @PostMapping(value = "aaa")
    public String testPositionAaa() {
   
        return "aaa";
    }

    @ApiOperation(value = "Test position 1", tags = {
   "position-test"}, position = 1)
    @RequestMapping(value = "bbb")
    public String testPositionBbb() {
   
        return "bbb";
    }
}

第2步：完成对 position的支持

拓展springfox.documentation.spring.web.readers.operation.ApiOperationReade类。

/*
 *  Copyright 2015-2019 the original author or authors.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *         http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

import com.google.common.base.Optional;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.RequestMethod;
import springfox.documentation.OperationNameGenerator;
import springfox.documentation.builders.OperationBuilder;
import springfox.documentation.service.Operation;
import springfox.documentation.spi.service.contexts.OperationContext;