常連

注目の的

社会貢献

質問力

自己紹介

こんにちは。
「全然わからない」は流石に言い過ぎなのですが。
やっぱり使いこなすには至らず質問させていただきます。

自分の理想的な使い方。
---
やはり、非同期処理の嫌なところは書いた順番に処理し終えて行ってくれないため、それを回避するためにpromiseを使いたいですよね。
「これをやったら、次にこれをやって、これをやったら次これをやる」というように。

色々ドキュメントを漁ってみて。この使い方が一番、上で言ったような使い方ができると思いました。
```nodejs
var p1 = new promise(function(resolve,reject){
  // any function
})
var p2 = p1.then(function(value){
  // any function
})
```
これで多分、p1をやったらp2をやるっていうコードは書けてると思うのですが。あってますかね？

不明点。
---
上記の使い方があっていれば不明点は三つです。（最後の一つはJSの初歩的な質問かもしれません。。。お付き合いいただけると助かります。）

①上記のような方法だと、p1内部の処理の完全な終了を待って、p2が発火するのでしょうか？
---

例えば、p1で値を受け取り、p2ではその値を用いて処理をします。と言ったものがあるとします。
（補足ですが、p1 p2で想定している処理は、外部のデータベースより値を参照し、取ってくると言った非同期処理です。今回の場合は[firebase.database](https://firebase.google.com/docs/reference/node/firebase.database?authuser=0)です。）
完全にp1の処理が終わってからp2の処理になってもらわないと、p2で参照した値はundefinedとなってしまいます。

②resolve,rejectってなんのためにあるの？
---
処理が成功するとresolve、エラーになるとrejectと言った漠然とした理解ですが。まずこれは正しいですか？

また。正しいと仮定して話を続けますが、promiseで連続させている次のfunction内に前の値を受け渡すのに、resolve,rejectを使用するのですか？
あまりなんのためにあるのか有用性が見えないのですが、どう便利なのでしょうか？

③連続したpromise内での変数の扱い。
---
これはpromiseに限った話ではなく、js全体の初歩的な話なのですが、ずっとviewのコーディングではstateでファイル内で共通して使う変数を管理してきたため。nodejsとして変数をいざ扱おうと思った時に混乱してしまいました。なので質問させてください。

以下の三つの①、②、③それぞれの出力はどうなりますでしょうか。
```nodejs
//there is root of file
var outside = "this is out"
any function(){
  var inside_any = "this is inside any"
  function(){
    var most_inside = "Hi"
  }
  function(){
    console.log(outside + inside_any + most_inside)
    //①はこの部分です。
  }

　var p1 = new promise(function(resolve){
    var inside_promise = "hello"
  })
  var p2 = p1.then(function(resolve){
    console.log(inside_promise)
    //②はこの部分です。
  })

  console.log(inside_any + most_inside + inside_promise)
  //③はこの部分です。
}
```
このような使い方は正しいのでしょうか？
現在どのように変数の受け渡しが可能か手探りでやっていますので、至らない質問かもしれませんが、教えていただけると助かります。
また、このような使い方以外が必要な場合、どのような処理で対応していますでしょうか？

Promiseの使い方がいろんなドキュメントを読んでも全然わからない。

言葉の由来や、その用語の持つ意味、あるいは語源や使われてきた理由などを知りたいです。

わたしは独学プログラミングなので言語や用語の深いところまで分かりません。
なぜこのような用語が使われているのかとか、業界用語的なものはまったくの無知です。

たまに以下のような用語や作法に出会う事があり、なぜこのように表現するのかとか、業界用語の由来的なものを知りたいと思っています。

もしお分かりになる方は、ぜひともご教示お願い致します。
こういう時によく使うとか、こうなんじゃないかなど推測でも構いません。
ぜひよろしくお願いします。
　

---
**1.
● hoge（ほげ）foo（ふー）**
　
　なぜ 「hoge」 や 「foo」 を使うのでしょうか？これは世界共通で使いますか？もし由来なども分かると嬉しいです

---
**2.
● APIを「叩く（たたく）」**

　「たたく」とはどういう意味ですか？なぜ「たたく」と表現するのでしょうか？

---

**3.
●コミットする**

　「コミットする」とは、プログラマーがこの言葉を使う時は、どんな時でしょうか？

---
**4.
●古い言語について「大文字」だけ、または「小文字と大文字の混在」**

　プログラマーの年齢！？によって書き方が違うように思えます。例えば「VALUE、INT、BOOL」など、大文字で書く人、
　あるいは「hInst、bRet」など、変数の頭に小文字を使うのはなぜですか？

---

**5.
●変数を「短く表現する」**

　「Number」→「Num」、「return、result」→「ret」、「function」→「func」

---

**6.
●行間を開けない**

　たまに古いタイプの言語でコメントとコードの行間をぴったり詰めて書いているのを見かけます。これはなぜですか？
　単純に見ずらいとは思うのですが、もしかすると昔はコードが多く詰めて書かざるを得なかったなどがあるのか？？知りたいです。

   （例）
　//コメントコメントコメントコメントコメントコメント
   BOOL InitInstance(HINSTANCE hInst, int nCmdShow)
   //コメントコメントコメントコメントコメントコメントコメント
　LRESULT CALLBACK WndProc(HWND, UINT, WPARAM, LPARAM);


---
**7.
●エンジニア と プログラマーの違い**

　語源からして職能が違うとは思いますが、エンジニアはプログラマーと同義と思っていますがどうでしょうか？
　日本と世界とでは違いはありますか？たとえば地位的な差があったとして、どちらかで呼び間違えた場合、失礼になったりしますか？

---

言葉の由来や、用語の持つ意味を知りたい

async/awaitが利用できるようになって非同期処理の例外もキャッチできるようになりましたが、それなりの規模のアプリケーションを作成するにあたり、どのように例外処理を行えばよいか迷っています。

例えば以下はKoaを利用したウェブアプリケーションの例になりますが、catchで受け取ったエラーオブジェクトを判定してエラーの種類によって適切な処理に振り分けるようなことをするのが一般的だと認識しています。

```
const Koa = require('koa')
const app = new Koa()

app.use(async (ctx, next) => {

  try {
    await next()

  } catch(e) {

    // エラーインスタンスの種類を判定して適切に処理
    if (e instanceof TypeError ||
        e instanceof RangeError ||
        e instanceof EvalError) {
      ctx.state = 500
    }
  }
})
```
上記のように標準のエラーを振り分ける場合はこれでよいと思っているのですが「アクセス権限が無い」といったエラーを独自に作成する場合には以下のようにする必要があると思います。

```
const Koa = require('koa')
const app = new Koa()

app.use(async (ctx, next) => {

  try {
    await next()

  } catch(e) {

    // 標準エラーを適切に処理
    if (e instanceof TypeError ||
        e instanceof RangeError ||
        e instanceof EvalError) {
      ctx.state = 500

    // 認証エラーを適切に処理
    } else if (e instanceof AuthError) {
      ctx.state = 403
    }
  }
})

// --------------------------------

const AuthError = require('AuthError')

app.use((ctx, next) => {
  ...
  if( !isAdmin ) throw new AuthError()
})
```

しかし私はこのようにエラー処理を行っている例を見たことが無いので、本当にこれでよいのか不安です。

調べてみたところほとんどのサンプルではエラーを以下のように投げていました。

```
throw new Error('auth error')
```

しかしこうしてしまうとキャッチしたエラーを種類別に判定することができなくなってしまいますよね？

もちろん`e.message`の内容を利用することでエラー別に適切な処理を行うことは不可能では無いと思っていますが、エラーメッセージは同じエラーでも内容が変わってしまうことがあると思うんです。

```
// 1234の値が状況によって変わるのでe.massegeをエラー種類判定に使えない
console.log(e.message) // "user 1234 is not found"
```

そのため、エラーの種類ごとに新しいエラークラスを作成してそのインスタンスを投げる方法しかないのだろうと思っているのですが、正直なところ大量のエラークラスを作成するのは面倒な作業だなと思っています。そこで、以下のように処理してしまえばいいのでは？と思いました。

```
const Koa = require('koa')
const app = new Koa()

app.use(async (ctx, next) => {

  try {
    await next()

  } catch(e) {

    // 標準エラーを適切に処理
    if (e.name == 'TypeError' ||
        e.name == 'RangeError' ||
        e.name == 'EvalError') {
      ctx.state = 500

    // 認証エラーを適切に処理
    } else if (e.name == 'AuthError') {
      ctx.state = 403
    }
  }
})

// --------------------------------

app.use((ctx, next) => {
  ...
  if( !isAdmin ) {
    let e = new Error('auth error')
    e.name = 'AuthError'
    throw e
  }
})
```

上記の方法では```e.name```の内容を書き換える必要があるのでカスマムエラークラスを作成していた時と比較して１行でエラーをthrowすることができていた部分が４行に膨れ上がっているため若干不満ですが、それ以外は満足のいくものになりました。

よし、これでいこう！と思ったのですが、本当にこれでいいのだろうか？皆様はどのように例外処理を行なっているのだろうということが気になって前に進むことができません。

本当にこのような方法で例外処理をしてもよいのでしょうか？

例えば、このような```e.name```を書き換える方法を使って例外を投げるモジュールを作成した場合、そのモジュールが、他のプロジェクトで利用することになった場合に問題は発生しないのだろうか？という新たな疑問が発生しました。

そもそも、一般的に例外処理はどのように行えばよいのでしょうか？
検索したのですが、あまりにも記事が出てこないので質問させていただきました。

よろしくお願いいたします。

JavaScriptの例外処理の実用について

Event情報の構造化マークアップの要件定義を行っています。
schema.orgや、Googleの構造化マークアップ支援ツールを確認すると、"startDate"が必須のようですが、毎週土曜日開催など、"startDate"がない場合の書き方を教えてください。

http://schema.org/Event
https://www.google.com/webmasters/markup-helper/?&hl=ja

JSON-LD Eventで毎週土曜日開催など、"startDate"がない場合の書き方を教えてください

```javascript
// 連想配列
var obj = {
  a1: 'asd',
  a2: 'sdf',
  a3: 'dfg',
  a4: 'fgh'
};

// 連想配列で検索する値
var searchValue = 'sdf';
```
上記の searchValue からキー「a2」を取得する方法はないでしょうか？
以下しか思いつかなかったのですが、もっと簡単で良い方法がありましたらご教授願います。
```javascript
var key = null;
var keys = Object.keys(obj);
for(var i=0; i<keys.length; i++)
{
  if (searchValue === obj[keys[i]])
  {
    key = keys[i];
  }
}
```

連想配列の値からキーを取得する方法はありませんか？

### 計算式を評価する

四則演算の計算式となる文字列を渡すと計算結果を返す関数を作りました(コードは文末の「参考リンク」から読めます)。

```JavaScript
evalCalculation('-1*3*.1+14/7*0.65'); // 1
```

`eval()` や `JSON.parse()` に倣い、文法違反な文字列を渡すと例外を返します。

```JavaScript
evalCalculation('*1+3');    // SyntaxError: An expression starts with an unexpected token: *
evalCalculation('1+3/');    // SyntaxError: An expression ends with an unexpected token: /
evalCalculation('1.1.1+3'); // SyntaxError: Illegal number: 1.1.1
```

### エラーメッセージをDOM上に出力する

この関数は電卓機能の為に作ったものなので早速組み込みました。
しかし、ユーザが電卓で不正な文字を入力したとしても通常はコンソールまで確認しませんのでエラーメッセージに気が付いてもらえません。
そこで、次のように修正する事を検討しました(下記は仮想コードであり、`calculator.js` には同コードはありません)。

```JavaScript
function outputErrorMessage (errorMessage) {  // 電卓上にエラーメッセージを出力する関数
  var messages = [
        [/^SyntaxError: An expression starts with an unexpected token: ([\s\S]+)$/, '文法違反: "$1" から始まる式は不正です'],
        [/^SyntaxError: An expression ends with an unexpected token: ([\s\S]+)$/, '文法違反: "$1" で終わる式は不正です'],
        [/^SyntaxError: Illegal number: ([\s\S]+)$/, '文法違反: "$1" は不正な数値です']
      ];

  for (var i = 0, l = messages.length, message, reg; i < l; ++i) {
    message = messages[i];
    reg = message[0];

    if (reg.test(errorMessage)) {
      console.error(errorMessage.replace(reg, message[1]));
      return;
    }
  }

  console.error(errorMessage);
}

function calc (expression) {
  try {
    return evalCalculation(expression);
  } catch (error) {
    outputErrorMessage(error.name + ': ' + error.message);
    return NaN;
  }
}

calc('*1+3');    // 文法違反: "*" から始まる式は不正です
calc('1+3/');    // 文法違反: "/" で終わる式は不正です
calc('1.1.1+3'); // 文法違反: "1.1.1" は不正な数値です
```

しかし、これでも出力されるエラーが初めに検出したエラーに限定されるという問題があり、次の状況が考えられます。

1. ユーザがクリップボードから `'*1.1.1+2/'` の式を貼り付ける -> エラー「文法違反: "*" から始まる式は不正です」
2. 1. のエラーを修正し、`1.1.1+2/` とする -> エラー「文法違反: "/" で終わる式は不正です」
3. 2. のエラーを修正し、`1.1.1+2` とする -> エラー「文法違反: "1.1.1" は不正な数値です」
4. 3. のエラーを修正し、`1.1+2` とする -> `3.1` が出力される

ユーザの事を考えるなら初めから全てのエラーメッセージを出力する設計が親切といえます。

### 私が考えた打開案

#### 要点

[1] 関数を一つにするか複数に分けるか
[2] 出力値を固定するか、変動するか
[3] 入力値を固定するか、変動するか

[1] は一つの関数の中で「エラーが発生するか、しないか」のような判断要素を関数に持たせて完結させるか、「`XMLHttpRequest` と Fetch API」のように根幹となる挙動が同じでも期待する結果が違う考えから関数を分けるか。

[2] は例えば、「エラーが発生した場合にエラーメッセージのリストを返し、エラーが発生なかった場合は `Number` 型を返す」というように条件に応じて出力値を変えるか、「エラーが発生したら `{value: NaN, error: ['エラーメッセージ1', 'エラーメッセージ2']}` を返し、エラーが発生しなかったら `{value: 12, error: []}` を返す」のように `Number` 型への拘りを止めて出力を固定するか。

[3] は例えば、「`evalCalculation('*1+2', true);` で関数呼び出ししたなら `SyntaxError` 例外を発生させずにエラーメッセージリストとなるオブジェクトを返し、`evalCalculation('*1+2', false);` または `evalCalculation('*1+2');` で関数呼び出ししたなら `SyntaxError` の例外を発生させる、というように入力条件に応じて挙動を変更するか、何らかの形で統一的なインターフェースを確立(一例として 2. の出力値を固定する事例が該当)して入力値を `evalCalculation('*1+2');` に固定するか。

#### 打開案コード事例

**(1) 関数を一つ、入力値を変動、出力値を変動(Number型、Object型)**

第二引数に「例外を発生させないフラグ変数」を指定します(規定動作は例外を発生させます)。

```JavaScript
evalCalculation('1+2', true);    // 3
evalCalculation('*1+2/', true);  // {value: NaN, errors: ['SyntaxError: An expression starts with an unexpected token: *', 'SyntaxError: An expression ends with an unexpected token: /']}

evalCalculation('1+2', false);    // 3
evalCalculation('*1+2/', false);  // SyntaxError: An expression starts with an unexpected token: *

evalCalculation('1+2');           // 3
evalCalculation('*1+2/');         // SyntaxError: An expression starts with an unexpected token: *
```

**(2) 関数を一つ、入力値を固定、出力値を固定(Object型)**

常に `Object` 型の値を返しますが、`valueOf` 関数、`toString` 関数を書き換える事でプリミティブ値は `Number` 型と同様の扱いとなります。
下記コードでは分かりやすいようにオブジェクト初期化子で書いていますが、実際にコーディングするなら内部的に `new CalculationFormula` のようなコンストラクタを作ることになると思います。

```JavaScript
var number1 = evalCalculation('1+2'),    // {valueOf: function () { return 3; }, toString: function () { return this.valueOf().toString(); }, errors: []}
    number2 = evalCalculation('*1+2/');  // {valueOf: function () { return NaN; }, toString: function () { return this.valueOf().toString(); },  errors: [['SyntaxError: An expression starts with an unexpected token: *', 'SyntaxError: An expression ends with an unexpected token: /']}

console.log(number1 * 2); // 6 (* 演算子は Number 型に変換して実行する為、number1 は 3 として扱われる)
document.body.appendChild(document.createTextNode(number1));  // createTextNode で String 型に変換される為、"3" が出力される
```

**(3) 関数を分ける、入力値を固定、出力値を固定(Number型、Promise)**

`evalCalculation()` は Number 型を返し、`evalCalculationPromise()` は Promise を返します。

```JavaScript
/**
 * evalCalculation()
 * Number 型を返す
 */
evalCalculation('1+2');    // {valueOf: function () { return 3; }, toString: function () { return this.valueOf().toString(); }, errors: []}
evalCalculation('*1+2/');  // SyntaxError: An expression starts with an unexpected token: *

/**
 * evalCalculationPromise()
 * Promise を返す
 */
function calc (expression) {
  evalCalculationPromise(expression).then(function (value) { // 成功時には value に Number 型の値が格納される
    console.log(value);
  }).catch(function (errors) {                               // 失敗時には errors にエラーメッセージの配列が格納される
    for (var i = 0, l = errors.length; i < l; ++i) {
      console.error(errors[i]);
    }
  });
}

calc('1+2');    // 成功: 3
calc('*1+2/');  // 失敗:  ['SyntaxError: An expression starts with an unexpected token: *', 'SyntaxError: An expression ends with an unexpected token: /']
```

**(4) 関数を一つ、入力値を固定、出力値を固定(Number型、Object型、Promise)**

(2), (3) の複合型。

```JavaScript
/**
 * Calculation.eval()
 * Number 型を返す
 */
Calculation.eval('1+2');    // 3
Calculation.eval('*1+2/');  // SyntaxError: An expression starts with an unexpected token: *

/**
 * Calculation()
 * Number 型を返す
 */
Calculation('1+2');    // 3
Calculation('*1+2/');  // SyntaxError: An expression starts with an unexpected token: *

/**
 * new Calculation
 * Object 型を返す
 */
new Calculation('1+2');    // {valueOf: function () { return 3; }, toString: function () { return this.valueOf().toString(); }, errors: []}
new Calculation('*1+2/');  // {valueOf: function () { return NaN; }, toString: function () { return this.valueOf().toString(); },  errors: [['SyntaxError: An expression starts with an unexpected token: *', 'SyntaxError: An expression ends with an unexpected token: /']}

/**
 * Calculation.evalPromise()
 * Promise を返す
 */
function calc (expression) {
  Calculation.evalPromise(expression).then(function (value) { // 成功時には value に Number 型の値が格納される
    console.log(value);
  }).catch(function (errors) {                               // 失敗時には errors にエラーメッセージの配列が格納される
    for (var i = 0, l = errors.length; i < l; ++i) {
      console.error(errors[i]);
    }
  });
}

calc('1+2');    // 成功: 3
calc('*1+2/');  // 失敗:  ['SyntaxError: An expression starts with an unexpected token: *', 'SyntaxError: An expression ends with an unexpected token: /']
```

#### 所感

直観的には (4) ですが、「名前」や「関数の置き場所」で悩みを抱えています。

- 「Number 型を返す関数」を `Calculation.eval`, `Calculation` のどちらにもっていくべきか
- `new Calculation` は必要？`Number()` と `new Number()` の関係性に持っていくと統一感が出る？
- `evalPromise` とは何ぞ？`Promise` を実行する？

私個人のポリシーとしては ECMAScript や DOM 等の標準 API のインターフェースを参考にして真似る事が多いのですが、同じような設計が見つかりませんでした。
`jQuery()` で与えられた引数に応じて挙動を変えるケース(関数を渡せば疑似 DOMContentLoaded のハンドラとなり、文字列を渡せば Selectors API となる)がありますが、ECMAScript を見ると関数の出力値は固定されており、入力値に応じて挙動や出力値が大きく変わるのは筋が良くないように感じています。

### エラーメッセージをまとめて出力する為の最適解は？

長くなりましたが、要件をまとめると次のようになります。

- エラーメッセージをまとめて出力したい
- 成功時/失敗時の出力値で最もわかりやすい設計は何か

一人ひとりで設計思想が違うので答えも一つではないと思いますが、皆さんであればどのように設計するでしょうか。
ご意見お聞かせください。

### 参考リンク

- [eval-calculation.js: 計算式の文字列を評価する - GitHub](https://gist.github.com/think49/54b074cab2145efddb48765652c74710)
- [calculator.js: 計算式を表示するシンプルな電卓 - GitHub](https://gist.github.com/think49/6aedea62463a741dde0a9ad2c9aa672e)

 エラーメッセージをまとめて出力する為の最適解は？

###前提・実現したいこと
JavaScriptの変数宣言について var と let の使い分けについて

質問 51551：JavaScriptでradioボタンで選択して背景色を変える(for loop を使って)
https://teratail.com/questions/51551
に関連して、変数の宣言の仕方 let について調べました。

参考資料： 
https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Statements/let#内部関数でのクリーンなコード

var や let の他にも、const という宣言の方法もあることがわかりました。

今のところ、let はすごく便利だった！という印象と、↑のような説明が、なんとなくわかるような気がするといったところなのですが、以前にvar で書いたものの中には、let や const では動かないものもあります。便利なことを知った分怖くなったところもあり、どのように使い分けたらよいのかを理解することができたらよいなと思っています。

###発生している問題・エラーメッセージ

```
エラーメッセージ
```

###該当のソースコード
```JavaScript
1.let でしか動かない

<form id="myForm">
  <input type="radio" name ="color" value="green">green
  <input type="radio" name ="color" value="red">red
</form> 

<script>
var c = document.getElementsByName('color');  
for(let i=0; i<c.length; i++){
    c[i].onclick= function(){document.body.style.background = c[i].value;
                 }
    }
  </script>

2.var でしか動かない

<p id="demo">default</p>
  
<script>
  var flws = ["Rose", "Tulip", "Pansy"];
  for (var i = 0, text = ""; i < flws.length; i++) {
      text += flws[i] + "<br>";
  }
  document.getElementById("demo").innerHTML = text;
</script>

```

###試したこと
課題に対してアプローチしたことを記載してください

###補足情報(言語/FW/ツール等のバージョンなど)
関連質問：質問： JavaScriptでradioボタンで選択して背景色を変える(for loop を使って) 
https://teratail.com/questions/51551

JavaScriptの変数宣言について　var と　let の使い分け

こんにちは。
Node.js(Express)の勉強を始めたばかりで、
疑問点があり、質問させてください。

app.paramで、オブジェクトで値を取得するには、
どのようにしたら良いでしょうか？

下記で動くと思ったのですが、
req.params.titleがundefinedになってしまいます。

```node.js
var express = require('express'),
	app = express();

app.set('views', __dirname + '/template');
app.set('view engine', 'ejs');

app.param(['id','page'], function(req, res, next, value) {
	var pagetitle = {
		profile: 'プロフィール',
		about: '概要'
	};
	req.params.title = pagetitle.page;
	next();
});

app.get('/:id/:page?', function(req, res) {
	if(req.params.page) {
		res.render('contents', {title: req.params.title});
	}
	else {
		res.send('no contents');
	}
});

app.listen(3000);
console.log('start');

```

解決方法をご教示いただけますと幸いです。
どうぞよろしくお願いいたします。

Express（Node.js）の、app.paramでの値の渡し方を教えてくださいmm

最近、EC2で画像投稿SNS(rails)を個人運営し始めました。

しかし、今まで実務経験がまったくなく、サーバーの管理に何をすれば良いかわかりません。

EC2でサーバーを運用していくには、何をする必要があるのでしょうか？

現時点で毎日していることは、

画像投稿時に/tmp/内にRackMultipart~とmagick-~というファイルが溜まってくるので、それをrm -rf で削除していくこと、

mysqlのデータをmysqldumpしてからS3にコピーすること、

インスタンスのスナップショットをとっていくことをしています。

サーバーの運用って何をするものなのですか？

オープンソースでwebサイトのプログラムを公開してみたいのですが、その場合、セキュリティーキーや、パスワードなどが誰にでも見えてしまうのは困るのですが、どうすればいいのでしょうか。

例えば、
phpとmysqlで通信する際のユーザー名とパスワードを隠したい。
javascriptからAjaxを使う。そのときにjavascriptで暗号化するときのキー。

ソースコードが見える場合のセキュリティーキーの書き方

現在、すでに作成済みのREST APIが大量にあるのですが、今後はswaggerでドキュメントを生成・管理していきたいと考えています。
作成済みの既存APIのwadlは用意しており、かつ実際にJSONでやり取りもできるのですが、これらの情報から既存APIに関するswaggerドキュメントを自動生成することは可能でしょうか？

swaggerのドキュメントを自動生成する方法

クライアントからAPIを呼び出す際の認証方式について教えてください。
管理画面からdeviseでログインして、クライアント（JS）からRailsで実装したAPIを呼び出しデータを取得する処理を実装しています。

APIでの認証についてですが、ログインしたタイミングでcookieに一意となるtokenをセットして、クライアントからtokenをAPIにリクエストすることで認証をかけています。
（テーブルにtokenが設定されていて、一致するかどうかで認証する仕組みです。）

懸念としては、cookieを盗まれることによるセキュリティの懸念があります。

上記のような場合、どのような認証をすることがセキュリティ的にも安全であるべき認証かというのがあれば教えてください。

Rails API認証方式について

jsonを返すAPIをつくっています。

APIの認証には、ヘッダにトークンを投げ、サーバーサイドのミドルウェアでトークンをチェックするという方式を取っています。

公開を想定したAPIなのですが、セキュリティについて分からないところがあります。


このAPIを自アプリケーション内で使用する際、アドミン用のトークンをヘッダに含めているのですが、それだとアドミン用のトークンを公開してしまうことになり、APIに認証を設ける意味がないと気づきました。


APIを公開する際には認証を必要としたいので、利用するユーザーそれぞれにAPIトークンを発行したいのですが、自アプリケーション内でAPIを安全に利用するにはどういう対策がありますでしょうか？

公開用とアドミン用のAPIを別に作成する必要があるのでしょうか？？

### 追記

追記: バックにはLaravel、フロントはReactを使っています。自作APIを利用するときは、基本的にはReactでAPIを叩いています。

追記： 皆様、有益な回答ありがとうございます。ググっても中々実装例が出てこなかったのでとても助かります。ただ、幅広い意見をお伺いしたいので今しばらく回答を募集中のままにさせていただきます。

### 改めて質問内容を整理します。

Laravelでアプリケーションを開発しており（以下、Laravel Appとします。Wantedlyのようなサービスです。）、「**Laravel App内で使用すること**」と「**外部のクライアントに利用してもらうこと**（外部クライアントが開発している別のアプリケーション等に利用してもらう、など）」を目的としたAPIを作っています。

このAPIを利用するには、ヘッダにLaravel Appが発行するユーザー（Laravel Appの利用者かつ登録者）それぞれが保持するAPI Tokenを含めてPOSTすることでLaravel APPのミドルウェアが認証処理を行い、レスポンスを返してくれます。

外部のクラアイントがAPIを利用する分には、このAPI Tokenでの認証方法で良いと思います。（回答者の方のご指摘通り、Tokenのチェック方法に留意する点はまだありますが・・）

しかし、この認証方法を設けてしまうと、Laravel App自身がAPIを使用することが難しくなってしまいます。
例えば、Laravel Appが自身がAPIを利用するためのアドミン用のAPI Tokenを用意しても、ヘッダ情報にAPI Tokenを含める必要があるため、Larave Appを利用する全てのユーザーにアドミン用のAPI Tokenが公開されてしまいます。


上記の利用目的において、APIの認証方法はどのようにすべきでしょうか？


### 考えている方法

* 公開用と内部で使用する用でAPIを分ける。内部で使用する用は非公開にする。

* アドミン用のAPI Tokenを利用せず、ユーザー（Laravel Appの利用者かつ登録者）のAPI Tokenを利用させる。本来、API Tokenは外部の別のアプリケーションの開発等に使用してもらうためのものを想定していたが、Laravel Appを利用する際も使用する仕様にする。
API TokenはLaravel Appに登録した時に自動で発行、いつでもリフレッシュ可能なものとする。

APIの認証方法と公開について

ユーザーIDをGetパラメータで受け取り、DBのテーブルを検索後、一致していれば後続の処理を行い、一致しなければ処理を中断させるという関数を作っております。

具体的にはrouter.getの最初の行でidCheck関数を呼び、idがDBのテーブルに一致すればtrue、一致しなければfalseを返します。

その後、returnでrouter.getに戻り、

if(!idCheck(req, res)) return;

という文でidの一致、不一致を判定しようと思ったのですが、どちらもif文に引っかかり、returnとなり、一致した場合でも後続の処理に入れません。

どのような書き方をすればtrueとfalseのif文を上手く動かすことが出来るのでしょうか？

よろしくお願いします。



/* Function test */
function idCheck(req, res) {
    User.find({ userid       : req.params.id }, function(err, items){
        if (err) {
            console.log(err);
            res.writeHead(401, {
                'Content-Type': 'text/plain'
            });
            res.end('failed.');
            return false;
        } else {
            if (items.length === 0) {
                console.log('failed. Not registered!');
                res.writeHead(401, {
                    'Content-Type': 'text/plain'
                });
                res.end('failed. Not registered!');
                return false;
            } else {
                console.log('successed!!');
                return true;
            }
        }
    });
}


/* GET users */
router.get('/api/users/:id', function(req, res) {
    if(!idCheck(req, res)) return;
    // 以下、処理
});