在 SwaggerUI 中休息 API 版本 header

Question

我想将 Springfox SwaggerUI 用于我的 Rest API (spring-mvc) 文档。我在@RequestMapping 注释中使用版本 header，但是如果我有相同方法的两个版本，在 SwaggerUI 中我只能看到一个。

例如：

@GetMapping(value = "/users", headers = "X-API-VERSION=1")
public List<User> getUsersV1(){...}

@GetMapping(value = "/users", headers = "X-API-VERSION=2")
public List<User> getUsersV2(){...}

以上代码仅导致 api 文档中可见的一种方法。

考虑到我的版本 header，是否有任何选项可以将 Swagger 配置为不同的端点？

Answer 1

Swagger 通过其端点识别服务。

每个功能必须响应不同的端点，headers 不应使用该功能。

如果您使用的是 REST 服务，请阅读一些关于 Restfull 的内容并遵循其原则。这个url可以帮到你：http://docs.oracle.com/javaee/6/tutorial/doc/gijqy.html

Answer 2

经过一些研究，我找到了解决问题的方法，也许它会对将来的人有所帮助。我使用 PathDecorator 向路径添加“#v”后缀。

现在我可以在生成的文档中看到我的所有方法。

@Component
@Order(value = Ordered.HIGHEST_PRECEDENCE + 70)
public class VersionPathDecorator implements PathDecorator {
    private final static Logger logger = LoggerFactory.getLogger(VersionPathDecorator.class);

@Override
public Function<String, String> decorator(PathContext context) {
    return (path) -> {
        StringBuilder sb = new StringBuilder(path);
        Field parent = null;
        try {
            parent = PathContext.class.getDeclaredField("parent");
            parent.setAccessible(true);
            RequestMappingContext rmc = (RequestMappingContext) parent.get(context);
            rmc.headers()
                    .stream()
                    .filter(h -> RequestHeader.X_API_VERSION.headerName.equals(h.getName()))
                    .map(NameValueExpression::getValue)
                    .findFirst()
                    .ifPresent(v -> sb.append("#v").append(v));

        } catch (NoSuchFieldException | IllegalAccessException e) {
            logger.error("path decoration failed", e);
        }

        return sb.toString();
    };
}

@Override
public boolean supports(DocumentationContext documentationContext) {
    return true;
}
}

在 SwaggerUI 中休息 API 版本 header

Rest API version header in SwaggerUI

rest

spring

spring-mvc

swagger

swagger-ui