How to change default swagger.json file path?

在使用Swagger进行API文档管理时，我们有时需要更改swagger.json文件的默认路径以满足特定的部署或安全要求。下面是一些在不同框架下更改swagger.json文件路径的方法。

1. 使用Swashbuckle（ASP.NET Core）

在ASP.NET Core中，如果使用Swashbuckle作为Swagger工具，可以通过在Startup.cs文件中配置Swagger生成选项来更改swagger.json文件的路径。以下是具体步骤：

csharp
public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // Enable middleware to serve generated Swagger as a JSON endpoint
    app.UseSwagger(c =>
    {
        c.RouteTemplate = "api-docs/{documentName}/swagger.json";
    });

    // Enable middleware to serve swagger-ui
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/api-docs/v1/swagger.json", "My API V1");
        c.RoutePrefix = "api-docs";
    });

    // Other configurations...
}

在上面的代码中，RouteTemplate属性被设置为 "api-docs/{documentName}/swagger.json"，这改变了swagger.json文件的默认路径。

2. 使用Spring Boot（Java）

在使用Spring Boot框架时，可以通过配置Spring MVC的资源处理器来修改Swagger UI资源的路径，包括swagger.json文件。以下是一个配置示例：

java
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/api-docs/**")
            .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/api-docs/swagger.json")
            .addResourceLocations("classpath:/META-INF/swagger/");
    }
}

在这段Java代码中，我们通过addResourceHandlers方法添加了对/api-docs/**和/api-docs/swagger.json路径的处理，从而改变了swagger.json文件的存放位置。

3. 使用Flask（Python）

在Python的Flask框架中使用Flasgger库时，可以如下配置swagger.json的路径：

python
from flasgger import Swagger
from flask import Flask

app = Flask(__name__)
swagger_config = {
    "headers": [],
    "specs": [
        {
            "endpoint": 'apispec_1',
            "route": '/api-docs.json',
            "rule_filter": lambda rule: True,  # all in
            "model_filter": lambda tag: True,  # all in
        }
    ],
    "static_url_path": "/flasgger_static",
    "swagger_ui": True,
    "specs_route": "/api-docs/"
}

swagger = Swagger(app, config=swagger_config)

在这个例子中，specs列表中的每个条目可以定义一个swagger规范的配置，其中route键指示了swagger.json的新路径。

结论

以上是在不同环境中更改swagger.json文件路径的几种方法。根据你使用的技术栈，你可以选择相应的配置方式。更改路径有时候是为了更好地与现有的API网关集成或遵守特定的安全规则。