Question

我正在尝试使用Swagger为我们正在构建的API创建API文档，而我之前从未使用过它。

Github上的文档说资源列表需要在 / api-docs ，各种资源文件需要在 / api-docs / books 等

这使得命名文件和文件夹非常棘手。我认为他们希望文件没有文件名，而不是有一个名为/ api-docs的文件夹，它必须是一个无扩展名的文件，那么你就不能把资源放在api-docs文件夹中，因为你可以' t调用该文件夹，因此建议使用名为/ listing。的文件夹。

这个文件夹没有出现在你的文档的URL结构中，但是它有点不可见，因为你将资源中的baseURL设置为正确的路径，但看起来它必须是一个绝对的路径，这很尴尬如果你想在多个服务器（本地和生产）上使用它。

也许我只是不明白，但这一切似乎绝对是疯了。

所以，我有两个问题......

1）我可以将资源列表文件和资源文件扩展为.json吗？这是有意义的，因为它是一个JSON文件。

2）我可以在资源文件的baseURL中使用资源列表文件的相对路径吗？

理想情况下，我的文件结构会比较扁平，就像这样...

/api-docs
    resources.json
    books.json
    films.json

Swagger足够灵活吗？

这是一个IIS服务器，如果这有任何区别（如果解决方案需要路由，例如）。

Answer 1

我能够将模型文件放到web根目录下的文件夹中，并可以像这样引用它们。

 $ref: '/models/model.yml#/MyObject'

相对路径也可以在没有前导斜杠的情况下工作。

   $ref: 'models/model.yml#/MyObject'

在model.yml中，我可以像这样

引用同一个文件中的其他对象

 $ref: '#/MyObject2'.

但是，我只能获得主要的swagger文件来导入模型文件。我无法获得一个模型文件来交叉引用另一个模型文件。

我使用的是Tomcat Web服务器，但原理是一样的。