第 5 章 ActiveDocs 和 OAuth
ActiveDocs 允许用户从一个位置测试和调用启用了 OAuth 的 API。
先决条件
- 您需要设置 Red Hat Single Sign-On 实例,并配置了 OpenID Connect 集成。有关如何设置它的信息,请参阅 OpenID Connect 集成 文档。
- 另外,您需要熟悉如何设置 ActiveDocs - 请参阅将 ActiveDocs 添加到 3scale 和创建 OpenAPI 规格。
5.1. 3scale 规格中的客户端凭证和资源所有者流示例
第一个示例是在 3scale 规格中使用 OAuth 2.0 客户端凭证流的 API。此 API 接受任何路径并返回有关请求的信息(path、请求标头、标头等)。Echo API 只能通过有效的访问令牌访问。API 的用户只能在为访问令牌交换其凭据(client_id
和 client_secret
)进行调用。
若要让用户能够从 ActiveDocs 调用 API,用户必须请求访问令牌。由于这仅仅是对 OAuth 授权服务器的调用,您可以为 OAuth 令牌端点创建 ActiveDocs 规格。这允许从 ActiveDocs 中调用此端点。在这种情况下,对于客户端凭证流,Swagger JSON 规格如下:
{ "swagger": "2.0", "info": { "version": "v1", "title": "OAuth for Echo API", "description": "OAuth2.0 Client Credentails Flow for authentication of our Echo API.", "contact": { "name": "API Support", "url": "http://www.swagger.io/support", "email": "support@swagger.io" } }, "host": "red-hat-sso-instance.example.com", "basePath": "/auth/realms/realm-example/protocol/openid-connect", "schemes": [ "http" ], "paths": { "/token": { "post": { "description": "This operation returns the access token for the API. You must call this before calling any other endpoints.", "operationId": "oauth", "parameters": [ { "name": "client_id", "description": "Your client id", "type": "string", "in": "query", "required": true }, { "name": "client_secret", "description": "Your client secret", "type": "string", "in": "query", "required": true }, { "name": "grant_type", "description": "OAuth2 Grant Type", "type": "string", "default": "client_credentials", "required": true, "in": "query", "enum": [ "client_credentials", "authorization_code", "refresh_token", "password" ] } ] } } } }
对于资源所有者 OAuth 流,请为用户名和密码添加参数,以及提供访问令牌所需的其他参数。对于这个客户端凭证流,您要发送 client_id 和 client_secret,这可从对签名用户的 3scale 值填充,以及 grant_type。
然后,在 Echo API 的 ActiveDocs 规格中,添加 access_token 参数,而不是 client_id 和 client_secret。
{ "swagger": "2.0", "info": { "version": "v1", "title": "Echo API", "description": "A simple API that accepts any path and returns information about the request", "contact": { "name": "API Support", "url": "http://www.swagger.io/support", "email": "support@swagger.io" } }, "host": "echo-api.3scale.net", "basePath": "/v1/words", "schemes": [ "http" ], "produces": [ "application/json" ], "paths": { "/{word}.json": { "get": { "description": "This operation returns information about the request (path, request parameters, headers, etc.), "operationId": "wordsGet", "summary": "Returns the path of a given word", "parameters": [ { "name": "word", "description": "The word related to the path", "type": "string", "in": "path", "required": true }, { "name": "access_token", "description": "Your access token", "type": "string", "in": "query", "required": true } ] } } } }
然后您可以在 Developer Portal 中包含 ActiveDocs。在这种情况下,由于您想要指定它们显示具有 OAuth 端点的顺序,因此类似如下:
{% active_docs version: "2.0" services: "oauth" %} <script type="text/javascript"> $(function () { window.swaggerUi.load(); // <-- loads first swagger-ui // do second swagger-ui var url = "/swagger/spec/echo-api.json"; window.anotherSwaggerUi = new SwaggerUi({ url: url, dom_id: "another-swagger-ui-container", supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'], onComplete: function(swaggerApi, swaggerUi) { $('#another-swagger-ui-container pre code').each(function(i, e) {hljs.highlightBlock(e)}); }, onFailure: function(data) { log("Unable to Load Echo-API-SwaggerUI"); }, docExpansion: "list", transport: function(httpClient, obj) { log("[swagger-ui]>>> custom transport."); return ApiDocsProxy.execute(httpClient, obj); } }); window.anotherSwaggerUi.load(); }); </script>