Document token information endpoint

In the previous section, we talked about integrating the doorkeeper gem for the bookmarker application, and also we documented api/v1/oauth/token with swagger. Doorkeeper gem also provides api/v1/oauth/token/info to get token information. You can check available oauth routes by running bundle exec rake routes command. This week we will document api/v1/oauth/token/info endpoint by using swagger.

Document ‘api/v1/oauth/token/info’ endpoint

api/v1/token/info endpoint basically gives us the necessary information about the provided token. The client-side developers use this endpoint to check the existing token’s validity and scope. (We don’t have any scope yet!)

Let’s say if we have an existing token that is ffxcdW1ktS59jbqWnRkfZRc6Vr9N16PyCQYKcNq-Su0 we can use it as following request to get the token information.

curl -H "Authorization: Bearer ffxcdW1ktS59jbqWnRkfZRc6Vr9N16PyCQYKcNq-Su0" \
        localhost:3000/api/v1/oauth/token/info

Basically, it’s a GET request with token specified in the header. The response should look as demonstrated below.

{
  "resource_owner_id": 1,
  "scope": [],
  "expires_in": 7147,
  "application": {
    "uid": null
  },
  "created_at": 1599829828
}

• resource_owner_id: ID of the resource owner, in our example, it’s a user ID.
• scope: We don’t have any scope yet, but we will have in the future to differentiate premium and free users for the bookmarker application.
• expires_in: Tells us after how many seconds this token will expire. By default, doorkeeper expires token in 2 hours. (You can change this in doorkeeper initializer.)
• application: We also don’t have any application but let’s say if we provide an API to external clients, then we could have identified them from their application uid.
• created_at: Timestamp value of the token’s creation.

Let’s document the endpoint by editing app/controllers/swagger/controllers/oauth_token_controller.rb file.

# frozen_string_literal: true

class Swagger::Controllers::OauthTokenController
  include Swagger::Blocks

  # ...

  swagger_path '/oauth/token/info' do
    operation :get do
      key :description, 'Show details about the token used for authentication'
      key :tags, [
        'oauth'
      ]

      parameter do
        key :name, :Authorization
        key :in, :header
        key :required, true
        schema do
          key :type, :string
        end
      end

      response 200 do
        key :description, 'Details about the specified token'
        schema do
          key :'$ref', :OauthTokenInfo
        end
      end

      response 401 do
        key :description, 'Unauthorized'
        schema do
          key :'$ref', :Unauthorized
        end
      end
    end
  end
end

We have defined the 200 response with OauthTokenInfo and Unauthorized classes in case of invalid token that we will create now.

# frozen_string_literal: true

module Swagger::Models::OauthTokenInfo
  include Swagger::Blocks

  swagger_schema :OauthTokenInfo do
    key :type, :object
    key :required, %i[resource_owner_id scope expires_in created_at]

    property :resource_owner_id do
      key :type, :integer
      key :format, :int64
    end

    property :scope do
      key :type, :array

      items do
        key :type, :string
      end
    end

    property :expires_in do
      key :type, :integer
    end

    property :created_at do
      key :type, :integer
      key :format, :int64
    end
  end
end

We will also define Unauthorized class inside of the app/controllers/swagger/models folder. You can test it with a non-existing token to see the structure of the response.

# frozen_string_literal: true

module Swagger::Models::Unauthorized
  include Swagger::Blocks

  swagger_schema :Unauthorized do
    key :type, :object

    property :error do
      key :type, :string
    end

    property :error_description do
      key :type, :string
    end

    property :state do
      key :type, :string
    end
  end
end

If you enter to the http://localhost:3000/swagger, you should see the documentation of api/v1/oauth/token/info endpoint in the oauth section.

Summary

We explained how we document api/v1/oauth/token/info endpoint by using swagger. You can find the source code of bookmarker application on github. You can also find the previous chapter here. From this chapter on, I would like to keep chapters as small as possible to make it easy to consume for readers. (Maybe it’s better to call them sections or modules instead of chapters.)

Thank you for reading! If you want to be notified when I publish a new chapter, you can follow me on twitter.