あれとアレは混ぜるな危険

日々精進をしているふり

Swashbuckle で Swagger を使うときの逆引き的なもの

どうもどうも、はるたまです。シルバーウィークですね。

最近、巷では Web API のドキュメントを Swagger で書くのが流行ってますね。Azure 界隈でも Web Apps は Swagger 活用している感じで、Logic Apps では必須になっていたりもします。
.NET のアプリケーションで Swagger といえば Swashbuckle なわけですが、ドキュメントを書こうとしたときにちょっと困っちゃうときがあると思いますので、率先して地雷を踏んできた結果をここに書き残しておきます。

前提条件

今回は、Azure Logic Apps のテンプレートでプロジェクトを作成しています。

作成されたプロジェクトには Swashbuckle があらかじめ NuGet でインストールされているので、最新の状態にアップデートしておきます。

今回は 5.2.1 がインストールされた状態になりますので、ここからスタートです。

FromUrl が指定された引数を必須にしたくない

URL パラメーターで受ける引数を作るために FromUri 属性をつけた引数をを持つ API を作成してみます。

        public IEnumerable<string> Get([FromUri] string someValue)
        {
            return new string[] { "value1", "value2" };
        }

これを Swagger で見ると

作成した値は「必須」になってしまいます。こうなると Swagger UI からこの API をテストするときに値を必ず設定しないと、エラーになってリクエストを投げてくれません。
URL パラメーターで受ける値は多くの場合に必須ではない値になると思いますが、こんな時は

        public IEnumerable<string> Get([FromUri] string someValue = "")
        {
            return new string[] { "value1", "value2" };
        }

このようにして、引数に対してデフォルト値を設定しておきます。こうすると Swagger UI で見た結果が

「required」がとれていますね。

レスポンスのステータスコードに対してドキュメントを書きたい

クライアントに レスポンスを返す際に 200 OK 以外のステータスでレスポンスを返す場合、Swashbuckle.Swagger.Annotations 名前空間にある SwaggerResponseAttribute クラスを使ってステータスコードに対してドキュメントを書くことができます。

        [SwaggerResponse(HttpStatusCode.NotFound, Description = "何もなければ404ですよ")]
        // GET api/values
        public IEnumerable<string> Get([FromUri] string someValue = "")
        {
            return new string[] { "value1", "value2" };
        }

こんな感じで Swagger　UI から見ると

という感じで、ステータスコードが追加できましたね。

クラスを引数で受ける場合にドキュメントが表示されるようにしたい

Post や Put の際には引数にクラスを指定して、リクエストの Body で送られてきたものを、こんな感じで受け取りますね。

    /// <summary>
    /// これがAPIの実体なのです
    /// </summary>
    public class ValuesController : ApiController
    {
        /// <summary>
        /// Postされると動くらしいよ
        /// </summary>
        /// <param name="value">値は何か知らない</param>
        public void Post([FromBody]Punipuni value)
        {
        }
    }

    /// <summary>
    /// 値を受けるためのクラス
    /// </summary>
    public class Punipuni
    {
        /// <summary>
        /// よく分かんないけど何か
        /// </summary>
        public string MyProperty { get; set; }
    }

この時に XML ドキュメントが出力されていればここにコメントの内容を表示したいのが人情というものですが、デフォルトでは表示されません。

これを表示させるためには、App_Start\SwaggerConfig.cs の同じような場所にこんなことを書いておきましょう。

// If you annonate Controllers and API Types with
// Xml comments (http://msdn.microsoft.com/en-us/library/b2s063f7(v=vs.110).aspx), you can incorporate
// those comments into the generated docs and UI. You can enable this by providing the path to one or
// more Xml comment files.
//
//c.IncludeXmlComments(GetXmlCommentsPath());
c.IncludeXmlComments(string.Format(@"{0}\bin\WebApplication1.XML", System.AppDomain.CurrentDomain.BaseDirectory));

もうちょっと気の利いたやり方はあるかもしれませんが、こんな感じで XML ドキュメントを指定しておくと

こんな感じで表示させることができます。
Web API の引数で受けるクラスが別のアセンブリで定義されている場合は XML ドキュメントも別ファイルで出力されるわけですが、IncludeXmlComments() は複数回呼んでも大丈夫です。
必要な分だけ呼んで XML ドキュメントを追加しましょう。

Vensmile IPC002 / W10 を買ってみた

こんばんは、はるたまです。最近下痢気味なんですが、原因がよくわからないので気にせずいつも通り生活しています。でも下痢だけど。

新しいおもちゃ「Vensmile IPC002 / W10」を手に入れたので自慢しておきます。

Vensmile IPC002 / W10 って何？

  • 8インチのタブレット PC から液晶だけを捨てて、ぎゅっと小さくしたようなパソコンです。
    (CPU Intel Atom Z3735F、メモリ 2GB、SSD 32GB)
  • でもバッテリーは(小さいですが)内蔵しています。
  • Windows 8.1 with Bing 入ってます。
  • そしてこれが $100 くらいで買える!!!!!

どこで買えるのか?

日本の Amazon で取り扱っている業者があるみたいですが、並行輸入品という扱いなので価格的には乗っかってくる感じですね。

Vensmile 極薄 MINI PC (Win8.1withBing/AtomZ3745F/2GB/32GBeMMC/3000mAh) iPC002 兼モバイルバッテリー [並行輸入品]

Vensmile 極薄 MINI PC (Win8.1withBing/AtomZ3745F/2GB/32GBeMMC/3000mAh) iPC002 兼モバイルバッテリー [並行輸入品]

海外から取り寄せるのが不安とか、思いついちゃったから今欲しいとか、そんな方にはこちらの選択肢のほうがいいかもしてません。

今回は AliExpress で偶然発見して、そのまま気を失っている間に発注していました。www.aliexpress.com
AliExpress の中でも「Vensmile IPC002」や「Vensmile W10」で検索するといろんな業者が扱っていますが、現状の 32GB 版であれば $100 を切るくらいの値段が最安値の目安になっています。
配送方法は無料配送になるシンガポール郵便を選択しました。予想配送時間が 15～39 日になっていたので気長に待つつもりでしたが、5月13日に発注と決済を済ませた後、送り先からの発送が完了して郵便をトラッキングするとこんな感じでした。

郵便自体は27日に我が家に到着しているので*1全部で14日かかっていますが、思ったよりも早く届いてご満悦です。

開封

箱を開けるといきなり本体と対面。ただし本体が微妙に汚れている感がありましたが、そんなことはご愛嬌なのです。気にしたら負けです。

本体の下には USB 出力の AC アダプタ、USB ケーブル、HDMI ケーブルが入っています。電源とケーブル類は完備されているので、あとはモニター・キーボード・マウスを接続すれば問題なく使い始めることができます。最後に申し訳程度のマニュアルで、箱の中のものはすべてです。

大きさと重さ

公式ではサイズ 148mm × 79mm x 9.2mm、重さは 340g です。余裕で持って歩くことができます。
iPhone 5s と比べてみると、大きさは一回り大きめ。おそらく iPhone 6 Plus に近い大きさです。

厚みに関しては iPhone 5s が 1.5 個分くらいの厚みです。

ちなみにこのサイズですが 3000mAh のバッテリーも入っているので、電源がない環境でもそれなりの時間運用することができます。初期状態の電源プランそのままで、BBench *2を使ってバッテリー満充電状態から残り 6% になってハイバネート状態になるまで111分でした。

ちなみにですが…

Web で検索してみると、同じ物なのに「Vensmile IPC002」という表記と「Vensmile W10」という表記が混ざっている感じですが、正式な表記は製造元のサイトを見ると「Vensmile IPC002」が正しいです。じゃあ「W10」がどこから来たかというと 公式 Facebook に答えのようなものがあって、元々製造していたモデルのアップデート版として現在出荷されているものを区別するため、新しいほうは「W10」がついているようです。
なので、今回調達したものは「Vensmile IPC002 / W10」が正しい表記になります。

電源を入れてセットアップ

電源を入れると普通に Windows 8.1 のインストールプロセスが開始されますので、いつも通りにセットアップします。Windows 自体は英語版ですが、インストール完了後に日本語化することは可能なので、気にせずセットアップしましょう。
システムのプロパティからはこのように見えます。

デバイスマネージャーからの見た目はこれ。

気になるストレージですが 21GB が使用可能になっていますので、結構入れられますね。

足りなかったら Micro SD カードを刺すこともできますので。

これが $100 ですよ奥さん!!!

*1:受け取れなかったので再配達で28日に受け取っている

*2:キーストローク間隔10秒 + Web巡回間隔60秒

Microsoft Store なら回線契約なしで Surface 3 を予約できるよ

こんばんは、はるたまです。

ついに発表された Surface 3 ですが、日本の小売向けには LTE モデルだけの供給で、WiFi モデルは法人だけというびっくりでしたね。
LTE モデルしか無いということで回線契約をしないといけないとか、Y!Mobile のお店じゃないと売ってないとか思われるかもしれませんが、普通に量販店での予約が始まっています。
もちろん Microsoft Store でも予約受付中です。
Microsoft Store (マイクロソフトストア)
気になる対応 LTE バンドは1と3と8ということで、ソフトバンク回線だけでなく、DoCoMo の電波(バンド1と3)でも使えそうな感じです。DoCoMo の電波を捕まえてくれるということは格安 SIM もいろいろ使えそうな感じですが、実際使えそうな感じですね。ちなみに Windows 8.1 での SIM に対する APN 設定ですが、基本的に刺している SIM に対応した電波から降ってくる APN 設定が選択肢として表示されます。でも「カスタム」を選択することで、強制的に APN を指定することができますので、DoCoMo の電波を使った格安 SIM の APN でもちゃんと設定することは可能です。

上の画面は Dell Venue 8 Pro の 3G 付きでの画面ですが、Windows 8.1 であれば同じような画面から変更できます。

Build と Ignite ～ Microsoft はパーソナルコンピュータの再定義をしたかもしれない

こんにちは、はるたまです。最近、寧ろ暑いよね。
最近 Microsoft は Build と Ignite という大きなイベントを2週連続で開催してくれましたが、そこで発表された内容の感想をしたためました。
つまり雑記です。

注意

この文章を書くにあたって、内容の全ては妄想でありポエムです。Microsoft さんの公式見解では全くありません。
もし書いている内容が当たっていたら運が良かったかな程度なもので。

前振り

ずいぶんな昔から振り返ると、ビル・ゲイツが Microsoft を創立した時のビジョンは「すべての人の机の上や家庭にコンピューターを」というものでした。windows.microsoft.com
そんな昔から40年というずいぶんな時間が経った今年2015年4月4日、Microsoft の創業者ビル・ゲイツが創立40周年にあたってのメモを Microsoft 全社員に送信したみたいです。gigazine.net
40年前に目指していたパーソナルコンピューターは、机や家庭にあるコンピューター、すなわちパソコンでした。しかし今の時代でのパーソナルコンピューターは、スマートフォンのようにポケットの中にいつも入っていて、常に電波でつながった状態で持って歩くという意味でのパーソナルなものになってしまいました。
現実が当時のビジョンを追い越したというのが実際に起ったことかも知れませんが、「パーソナルコンピュータ=パソコン」の時代から「パーソナルコンピューター=スマートフォン」の時代まで存続し続けていた Microsoft というのもすごいですね。そりゃ40年もやってればそうなりますよ。
一方で40年前の当初思い描いていた「パーソナルコンピューター=パソコン」の時代が終わりそうなっている今、スマートフォンのようなパーソナルコンピューターの市場では Android や iOS にやられているというのも事実です。
Microsoft にとってのパーソナルコンピュータとは何なのかといういうことを、もう一度考えなおさないといけないタイミングがやってきたのかもしれません。

Build でリリースされたこと

そうして始まった Build 1日目のキーノート。Continuum という機能が Windows Phone に搭載されるというアナウンスがありました。

HDMI で外部出力可能な Windows Phone に Bluetooth のマウスとキーボードをつないで、端末の画面ではなく外部出力画面で Universal Application が操作可能になるというもの。

これだけ聞くと別になんというわけでもありませんが、デモに使われていたアプリケーションがなんと PowerPoint、Outlook、Excel でした。

つまり Microsoft はスマートフォンで完全にお仕事が出来る世界を目指しているということで。端末は BYOD して、スマホアプリでお仕事なんて甘っちょろいものじゃないんですよ。Continuum という単語の元々の意味は「連続体*1」のような意味ですが、ここまで連続的だとびっくりです。
デモの見た目にはパソコンとスマートフォンのエクスペリエンスを連続的に見せています。ただし事の本質は、Office アプリケーションがパソコンではなくスマートフォンという常に持って歩ける機械を使って連続的に見えていることかもしれません。言うまでもなく Office で見ているデータはスマートフォンの中やクラウドにいるため、常にデータは同期されているのが当たり前という前提コミコミの話。

そしてパソコンはどうなる?

40年くらい前に、Microsoft は Intel や IBM などと一緒になってパソコンという市場を作り、ここまで発展させてきました。
Microsoft が今後も存続するために、これまでに作り上げてきた現在のパソコンを自分の手で殺しにかからないといけないというのが、Micorsoft にとって最大の宿題だったと思います。
今回のキーノートで Office のエクスペリエンスを一貫して提供する、つまり、普通の会社員が毎日仕事をしている環境を一貫して提供するということが Microsoft にとってパーソナルコンピューターの役目であるというような解釈が見えたような気がした、創立40年目のキーノートだったんじゃないかと考えています。
そういえば、サティア・ナデラも「マイクロソフトのコアは、モバイルファースト、クラウドファーストの世界におけるプロダクティビティソリューションとプラットフォームの提供企業であることです。」って言ってましたねぇ。
Bold Ambition & Our Core (大胆な理想、そして、マイクロソフトのコア) | News Center Japan

*1:数学的な意味での「連続」という用法が元々の意味では多いような気がする

ASUS MeMO Pad 7 が T-Mobile の LTE を捕まえてくれた

こんにちは、はるたまです。
先日サンフランシスコに行ってきましたが、電波と電気がなくなると生きていけない種族の我々は、特に海外の電波事情が気になるところです。
今回のサンフランシスコ出張へは T-Mobile の SIM と、T-Mobile の LTE が使いたくて調達した ASUS MeMO Pad 7 を持って、ちゃんと LTE の電波を捕まえて通信ができるかを試してきました。

ASUS MeMO Pad 7 LTE モデル ( Android 4.4.2 / 7 inch / Atom Z3560 / eMMC 16GB / 2GB / LTE対応 / microSIMスロット / ゴールド ) ME572CL-GD16LTE

ASUS MeMO Pad 7 LTE モデル ( Android 4.4.2 / 7 inch / Atom Z3560 / eMMC 16GB / 2GB / LTE対応 / microSIMスロット / ゴールド ) ME572CL-GD16LTE

サンフランシスコに到着して、MeMO Pad 7 へ T-Mobile の SIM を刺して電源を入れると…

あっさり LTE を捕まえてくれます。

もちろんキャリアは T-Mobile で。

APN は T-Mobile のものが降ってきて、自動的にこれが選択されていました。
(上の「T-Mobile」という APN は自分で事前に設定しておいたもの。下の「T-Mobile US LTE」が降ってきた APN。)

ちなみに速度ですが、調子が良ければこの位の数字が出ます。

ただしこの数字自体は夜中の1時くらいでの数字なので、当然昼間はもっと遅くなります。普通の場所であれば下りで 3M くらいの速度が出ていたので、基本的には困らない速度で通信ができていました。
イベントのキーノートスピーチ会場で使えないか試してみましたが、当然というか予想通りもはや息をしていませんでした。どこの国の電波でも混雑してしまえば同じような感じなので、過信してはいけないということで。