Improve generation of README which has long description

[ackintosh]

Description

With the spec which has a long description like below, README generated from the spec is very hard to read as new line contained in {{appDescription}} is stripped. 😢

• spec

which has markdown-formatted description.
https://api.shop-pro.jp/v1/swagger.json

{
  "swagger": "2.0",
  "info": {
    "title": "カラーミーショップ API",
    "description": "# カラーミーショップ API\n\n[カラーミーショップ](https://shop-pro.jp) APIでは、受注の検索や商品情報の更新を行うことができます。\n\n## 利用手順\n\nはじめに、カラーミーデベロッパーアカウントを用意します。[デベロッパー登録ページ](https://api.shop-pro.jp/developers/sign_up)から登録してください。\n\n次に、[登録ページ](https://api.shop-pro.jp/oauth/applications/new)からアプリケーション登録を行ってください。\nスマートフォンのWebViewを利用する場合は、リダイレクトURLに`urn:ietf:wg:oauth:2.0:oob`を入力してください。\n\nその後、カラーミーショップアカウントの認証ページを開きます。認証ページのURLは、`https://api.shop-pro.jp/oauth/authorize`に必要なパラメータをつけたものです。\n\n|パラメータ名|値|\n|---|---|\n|`client_id`|アプリケーション詳細画面で確認できるクライアントID|\n|`response_type`|\"code\"という文字列|\n|`scope`| 別表参照|\n|`redirect_url`|アプリケーション登録時に入力したリダイレクトURL|\n\n`scope`は、以下のうち、アプリケーションが利用したい機能をスペース区切りで指定してください。\n\n|スコープ|機能|\n|---|---|\n|`read_products`|商品データの参照|\n|`write_products`|在庫データの更新|\n|`read_sales`|受注・顧客データの参照|\n|`write_sales`|受注データの更新|\n\n以下のようなURLとなります。\n\n```\nhttps://api.shop-pro.jp/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URL&response_type=code&scope=read_products%20write_products\n```\n\n初めてこのページを訪れる場合は、カラーミーショップアカウントのIDとパスワードの入力を求められます。\n承認ボタンを押すと、このアプリケーションがショップのデータにアクセスすることが許可され、リダイレクトURLへリダイレクトされます。\n\n承認された場合は、`code`というクエリパラメータに認可コードが付与されます。承認がキャンセルされた、またはエラーが起きた場合は、\n`error`パラメータにエラーの内容を表す文字列が与えられます。\n\nアプリケーション登録時のリダイレクトURLに`urn:ietf:wg:oauth:2.0:oob`を指定した場合は、以下のようなURLにリダイレクトされます。\n末尾のパスが認可コードになっています。\n\n```\nhttps://api.shop-pro.jp/oauth/authorize/AUTH_CODE\n```\n\n認可コードの有効期限は発行から10分間です。\n\n最後に、認可コードとアクセストークンを交換します。以下のパラメータを付けて、`https://api.shop-pro.jp/oauth/token`へリクエストを送ります。\n\n|パラメータ名|値|\n|---|---|\n|`client_id`|アプリケーション詳細画面に表示されているクライアントID|\n|`client_secret`|アプリケーション詳細画面に表示されているクライアントシークレット|\n|`code`|取得した認可コード|\n|`grant_type`|\"authorization_code\"という文字列|\n|`redirect_uri`|アプリケーション登録時に入力したリダイレクトURL|\n\n```console\n# curl での例\n\n$ curl -X POST \\\n  -d'client_id=CLIENT_ID' \\\n  -d'client_secret=CLIENT_SECRET' \\\n  -d'code=CODE' \\\n  -d'grant_type=authorization_code'   \\\n  -d'redirect_uri=REDIRECT_URI'  \\\n  'https://api.shop-pro.jp/oauth/token'\n```\n\nリクエストが成功すると、以下のようなJSONが返ってきます。\n\n```json\n{\n  \"access_token\": \"d461ab8XXXXXXXXXXXXXXXXXXXXXXXXX\",\n  \"token_type\": \"bearer\",\n  \"scope\": \"read_products write_products\"\n}\n```\n\nアクセストークンに有効期限はありませんが、許可済みアプリケーション一覧画面から失効させることができます。なお、同じ認可コードをアクセストークンに交換できるのは1度だけです。\n\n取得したアクセストークンは、Authorizationヘッダに入れて使用します。以下にショップ情報を取得する際の例を示します。\n\n```console\n# curlの例\n\n$ curl -H 'Authorization: Bearer d461ab8XXXXXXXXXXXXXXXXXXXXXXXXX' https://api.shop-pro.jp/v1/shop.json\n```\n\n## エラー\n\nカラーミーショップAPI v1では\n\n- エラーコード\n- エラーメッセージ\n- ステータスコード\n\nの配列でエラーを表現します。以下に例を示します。\n\n```json\n{\n  \"errors\": [\n    {\n      \"code\": 404100,\n      \"message\": \"レコードが見つかりませんでした。\",\n      \"status\": 404\n    }\n  ]\n}\n```\n",
    "termsOfService": "https://api.shop-pro.jp/developers/tos",
    "contact": {

• README generated from the spec

The description is hard to read as the new line is stripped.
https://github.com/ackintosh/colormeshop-ruby/blob/6b5e3dd638d0f5e449a9aa24769c1dfbf012f781/README.md

---

We have also {{unescapedAppDescription}}, but want to keep the docs as safe as possible. (Only new line is needed.)

openapi-generator version

latest master

OpenAPI declaration file content or url

https://api.shop-pro.jp/v1/swagger.json

Suggest a fix/enhancement

Make available a new tag which allows new line named like {{appDescriptionWithNewLine}}.

Any thoughts?

[ackintosh]

I was thinking about that allowing new line in "{{appDescription}}" . 💭

{{appDescription}} is also used at source code (doc comment), so allowing new line in {{appDescription}} may has risk:
Allowing new line in {{appDescription}} may cause unintended behavior of api/model on the languages that values new line and indentation.

I can not yet assume a specific case where security problems will occur if we allow new line in doc comment... However, the problem usually comes from an unexpected place.

So I think make available a new tag is the best way. The new tag can satisfy the both of requirement allowing new line at description and limitation of where we allow new line (only README).

[wing328]

{{appDescription}} is also used at source code (doc comment), so allowing new line in {{appDescription}} may has risk:

Totally agree. If my memory serves me well, that's the primary reason why we removed the new line in the appDescription tag.