Generate mappings for APIs

[EdricChan03]

Overview

Currently, the generator plugin only downloads the root discovery, and then downloads every discovery that is included in the root discovery.

Tasks

• Work out an ideal API structure (example: the Google API Java Client Services library)
• Use a library that auto-generates Kotlin code (e.g. Square's KotlinPoet, which can be used with Google's Kotlin Symbol Processing (KSP))
• Allow for devs to specify how the files should be created, and their contents

For consideration

• Compile-time checking for OAuth scopes
  • Something like an opt-in annotation might suffice, but how exactly do we surface the required OAuth scopes that an API might need?

[EdricChan03]

I've decided on using interfaces for the services - here's what an API's interface would look like (I'm using the Discovery API as an example):

@file:Generated(revision = "20200806")

package io.github.edricchan03.koogle_api.services.discovery

import io.github.edricchan03.koogle_api.annotation.Generated
import io.github.edricchan03.koogle_api.services.discovery.apis.getrest.GetRestHttpMethodBuilder
import io.github.edricchan03.koogle_api.services.discovery.apis.getrest.models.RestDescription
import io.github.edricchan03.koogle_api.services.discovery.apis.list.ListHttpMethodBuilder
import io.github.edricchan03.koogle_api.services.discovery.apis.list.models.DirectoryList

public interface DiscoveryService {
    /** The "apis" collection of methods. */
    public interface Apis {
        /**
         * Retrieve the description of a particular version of an api.
         * @param methodInit Configuration to be passed to [GetRestHttpMethodBuilder].
         * @see GetRestHttpMethodBuilder
         * @see getRest
         * @return The resulting JSON data as a serialized [RestDescription].
         * @since 0.1.0
         */
        public suspend fun getRest(methodInit: GetRestHttpMethodBuilder.() -> Unit): RestDescription

        /**
         * Retrieve the description of a particular version of an api.
         * @param api The name of the API.
         * @param version the version of the API.
         * @return The resulting JSON data as a serialized [RestDescription].
         * @since 0.1.0
         */
        public suspend fun getRest(api: String, version: String): RestDescription = getRest {
            path {
                this.api = api
                this.version = version
            }
        }

        /**
         * Retrieve the list of APIs supported at this endpoint.
         * @param methodInit Configuration to be passed to [ListHttpMethodBuilder].
         * @return The resulting JSON data as a serialized [DirectoryList].
         * @since 0.1.0
         */
        public suspend fun list(methodInit: ListHttpMethodBuilder.() -> Unit): DirectoryList

        /**
         * Retrieve the list of APIs supported at this endpoint.
         * @param name Only include APIs with the given name.
         * @param preferred Return only the preferred version of an API.
         * @return The resulting JSON data as a serialized [DirectoryList].
         * @since 0.1.0
         */
        public suspend fun list(
            name: String? = null, preferred: Boolean = false
        ): DirectoryList = list {
            queryParameters {
                this.name = name
                this.preferred = preferred
            }
        }
    }

    public companion object {
        /**
         * The default encoded root URL of the service. This is determined when the library is generated
         * and normally should not be changed.
         * @since 0.1.0
         */
        public const val DEFAULT_ROOT_URL: String = "https://www.googleapis.com/"

        /**
         * The default encoded service path of the service. This is determined when the library is
         * generated and normally should not be changed.
         * @since 0.1.0
         */
        public const val DEFAULT_SERVICE_PATH: String = "discovery/v1/"

        /**
         * The default encoded base URL of the service. This is determined when the library is generated
         * and normally should not be changed.
         * @since 0.1.0
         */
        public const val DEFAULT_BASE_URL: String = DEFAULT_ROOT_URL + DEFAULT_SERVICE_PATH
    }
}

This allows for the following syntax:

suspend fun example() {
  // Named parameters
  val result = discovery.getRest(api = "discovery", version = "v1")
  // DSL syntax
  val result2 = discovery.getRest {
    // HTTP headers
    headers {
      // ...
    }
    // Customise the resulting HTTP path
    path {
      api = "discovery"
      version = "v1"
    }
    // Customise the resulting query parameters
    query {
      // ...
    }
  }
}

The values are currently defined as according to the REST description - to manually specify a custom URL/data, consider using Ktor/any other suitable HTTP client directly.