5장. ActiveDocs 및 OAuth

이 첫 번째 예는 3scale 사양의 OAuth 2.0 클라이언트 인증 정보 흐름을 사용하는 API용입니다. 이 API는 경로를 수락하고 요청에 대한 정보(경로, 요청 매개변수, 헤더 등)를 반환합니다. 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 사양에 client _ id 및 client_ secret 대신 access_ token 매개 변수를 추가합니다.

{
  "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
          }
        ]
      }
    }
  }
}

그런 다음 정상적으로 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>