关于AppEngine OpenAPI 2.0文档缺失WebServlet与securityDefinitions的问询

我来帮你理清这几个关于App Engine OpenAPI 2.0的问题，结合实践经验给你解决方案：

关于securityDefinitions #

OpenAPI 2.0中的securityDefinitions无法通过自动生成工具直接获取，必须手动添加——不管你用原生Servlet还是Endpoints Framework。如果是用Endpoints Framework，你可以通过代码注解配置，否则就得直接编辑openapi.yaml或openapi.json文件。

手动配置示例（yaml格式）：

securityDefinitions:
  google_id_token:
    type: "oauth2"
    authorizationUrl: ""
    flow: "implicit"
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v3/certs"
    x-google-audiences: "your-client-id.apps.googleusercontent.com"

关于WebServlet方法 #

如果你的接口是基于原生HttpServlet开发的，App Engine的自动生成工具不会把这些方法纳入OpenAPI文档——因为原生Servlet不支持Endpoints的注解扫描。这时候有两种选择：

• 直接手动在OpenAPI文档中添加对应的paths和operation节点，把Servlet的接口定义补全
• 将原生Servlet迁移到Google Cloud Endpoints Framework，通过注解自动生成包含方法定义的OpenAPI文档

首先要明确：@ApiMethod是Endpoints Framework的专属注解，不能直接用于原生HttpServlet。你需要把原生Servlet的逻辑迁移到Endpoints的API类中，示例如下：

第一步：添加Endpoints依赖（Maven为例） #

<dependency>
  <groupId>com.google.endpoints</groupId>
  <artifactId>endpoints-framework</artifactId>
  <version>2.2.2</version>
</dependency>

第二步：编写API类（替代原生Servlet） #

import com.google.api.server.spi.config.Api;
import com.google.api.server.spi.config.ApiMethod;
import com.google.api.server.spi.config.Named;
import com.google.api.server.spi.response.NotFoundException;

import javax.servlet.http.HttpServletRequest;

@Api(
    name = "myApi",
    version = "v1",
    description = "我的App Engine API服务",
    // 在这里配置securityDefinitions，会自动同步到OpenAPI文档
    securityDefinitions = {
        @ApiAuth(
            name = "google_id_token",
            type = "oauth2",
            issuer = "https://accounts.google.com",
            jwksUri = "https://www.googleapis.com/oauth2/v3/certs",
            audiences = "your-client-id.apps.googleusercontent.com"
        )
    }
)
public class MyApiService {

    // 对应原Servlet的GET请求逻辑
    @ApiMethod(
        name = "resource.get",
        path = "resource/{id}",
        httpMethod = ApiMethod.HttpMethod.GET
    )
    public Resource getResource(@Named("id") String id, HttpServletRequest request) throws NotFoundException {
        // 原Servlet中的业务逻辑迁移到这里
        Resource targetResource = fetchResourceById(id);
        if (targetResource == null) {
            throw new NotFoundException("资源不存在");
        }
        return targetResource;
    }

    // 对应原Servlet的POST请求逻辑
    @ApiMethod(
        name = "resource.create",
        path = "resource",
        httpMethod = ApiMethod.HttpMethod.POST
    )
    public Resource createResource(Resource newResource) {
        // 原Servlet中的创建逻辑迁移到这里
        return saveNewResource(newResource);
    }
}

第三步：配置Endpoints Servlet（web.xml） #

<servlet>
    <servlet-name>EndpointsServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
    <init-param>
        <param-name>services</param-name>
        <param-value>com.example.MyApiService</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>EndpointsServlet</servlet-name>
    <url-pattern>/_ah/api/*</url-pattern>
</servlet-mapping>

部署后，访问https://你的应用ID.appspot.com/_ah/api/discovery/v1/apis/myApi/v1/rest就能获取包含所有@ApiMethod定义和securityDefinitions的完整OpenAPI文档了。

内容的提问来源于stack exchange，提问作者srv