API 記述言語やドキュメンテーションツールの比較(Swagger、API Blueprint、RAML)

背景

「最近」というには最近すぎる気がしますが、今日のシステム開発では、変化し続ける要件に対応するため、システム自体にも柔軟性がもとめられています。

その中でも、サーバーとクライアント、またはサーバー同士のやり取りのためのインターフェイスである Web API(以下、小面倒なので平たく API と呼びます)は Web システムにとって、もはや欠かせないものだと思います。
その API を設計する際には多くの人が RESTful API や GraphQL を採用するでしょう。

しかし、採用したものの設計方針が人によって微妙にバラつきがあったり、ドキュメントの運用保守ができていなかったり、モックや API コンソールを作らなければならなかったり、ドキュメントからではなくコードから書く人がいたりと、開発規模や状況に応じていろいろなレベルの課題が存在します。

そろそろ上記のようなことは API 設計が終わった段階で 8 割くらい終わっている状態にしたいですよね。
API の保守は、ソースコードそのものだけでなく、ドキュメント、API コンソールやスタブ、単体テストなど影響が広範囲に及びます。
それらの解決の手助けをしてくれるのが API ドキュメンテーションツール(一部では API フレームワークとも呼ばれている?)です。

API ドキュメンテーションツールとは

API ドキュメンテーションツールは、設計から開発、ドキュメント生成までをワンストップでサポートします。
最近のツールでいうと、そのツールが対応している記述方式(API 記述言語というべきか?)で API を定義することで、以下のようなことができます。

つづきをみる

Kotlin: 'Classpath entry points to a non-existent location: /path/to/app/src/main/kotlin'

Kotlin で記述したテストを実行した際に下記の Warning が発生。
(ちなみに Kotlin のバージョンは 1.2.50)

w: Classpath entry points to a non-existent location: /path/to/app/src/main/kotlin

調べてみると Kotlin 1.2.51 で修正済み (参考)ということ。

この file.exists() が本質的な対応コードかな?

参考 URL

Java から Kotlin のメソッドを呼び出すときに気をつけること(@JvmStatic)

ちょっとした「こういうもんなのか」ということがあったので備忘録的に残しておく。

Kotlin で書かれたオブジェクト「DataStore」があるとする。

// kotlin
object DataStore {

    private val shared: DataStore = DataStore

    fun shared(): DataStore {
        return shared
    }

    fun setup(context: Context) {
    }

}

このクラスの shared メソッドを Java から呼び出す場合は INSTANCE を経由して呼び出す必要がある。

// java
DataStore.INSTANCE.shared().setup(context);

しかし、 DataStore の sharedJvmStatic アノテーションを付けると…、

// kotlin
object DataStore {

    private val shared: DataStore = DataStore

    @JvmStatic
    fun shared(): DataStore {
        return shared
    }

    fun setup(context: Context) {
    }

}

INSTANCE を経由せずに呼び出すことができる。

// java
DataStore.shared().setup(context);

詳しい調査・解説はまた時間があるときに。

参考 URL

iOS 12 Safari のユーザーエージェント - iPhone, iPad, iPod touch

iOS バージョン 12 系のユーザーエージェント一覧です。

iOS 12.0

// iPhone
Mozilla/5.0 (iPhone; CPU iPhone OS 12_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0 Mobile/15E148 Safari/604.1

// iPad
Mozilla/5.0 (iPad; CPU OS 12_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0 Mobile/15E148 Safari/604.1

// iPod touch
Mozilla/5.0 (iPod touch; CPU iPhone OS 12_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0 Mobile/15E148 Safari/604.1

iOS 12.0.1

// iPhone
Mozilla/5.0 (iPhone; CPU iPhone OS 12_0_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0 Mobile/15E148 Safari/604.1

// iPad
Mozilla/5.0 (iPad; CPU OS 12_0_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0 Mobile/15E148 Safari/604.1

// iPod touch
Mozilla/5.0 (iPod touch; CPU iPhone OS 12_0_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.0 Mobile/15E148 Safari/604.1

iOS 12 以外のユーザーエージェント

Twitter: コールバック URL(Callback URL not approved for this client application ...)

自分が管理しているサービスで Twitter ログインまわりで下記のアプリケーションエラーが発生していたため調べてみました。

<?xml version="1.0" encoding="UTF-8"?>
<errors>
    <error code="415">Callback URL not approved for this client application. Approved callback URLs can be adjusted in your application settings</error>
</errors>

どうやらこのエラー、調べてみると事前にお知らせがあった内容のようで、下の URL がその内容らしいです。

Action REQUIRED - Sign in with Twitter users must whitelist callback URLs

URL の中身をみてみます。

つづきをみる