Swagger API文件的書寫規則(正規化)非常的強 ，好處是自動生成對應的視覺化檔案,方便查閱,方便前後端分離和介面測試，但是卻給書寫者帶來了很大的不方便,但是我們硬著頭皮也要寫下去，因為我還年輕

首先安裝，然後nodejs.cmd進入

到安裝目錄下 : C:/User

1.書寫格式

要求檢查每一個空格和符號 縮排必須要相同，否則雙重報錯( 1.code報錯 2.視覺化檔案報錯 )，要求極為嚴苛

我採用yaml書寫方式，也是官方推薦的形式

swagger: '2.0'
info:
version: 1.0.0
title: Simple API
description: A simple API to learn how to write OpenAPI Specification
schemes:
 - http
 - https
host: simple.api
basePath: /openapi01
paths:
/persons:
get:
 summary: Get some persons
 description: Returns a list containing all persons.This list supports paging.
 parameters:
       - name: pageSize
     in: query
     description: Number of persons returned
     type: integer
       - name: pageNumber
     in: query
     description: Page number
     type: integer
 responses:
   '200':
     description: A list of Person
     schema:
       $ref: '#/definitions/Persons'
post:
 summary: Create a person
 description: Add a new person to the persons list .
 parameters:
       - name: person
     in: body
     description: The person to create .
     schema:
       $ref: '#/definitions/Person'
 responses:
   '204':
     description: person created successfully
   '400':
     description: Person creared failed
'/persons/{username}':
get:
 summary: Gets a person
 description: Returns a single person for its username
 parameters:
       - name: username
     in: path
     required: true
     description: The person's username
     type: string
 responses:
   '200':
     description: A person
     schema:
       $ref: '#/definitions/Person'
   '404':
     description: The person does not exists.
definitions:
Person:
required:
     - username
properties:
 firstname:
   type: string
 lastname:
   type: string
 username:
   type: string
Persons:
type: array
########這是使用定義來定義另外一個定義 相當於 類的欄位是另一個類的物件
items:
 $ref: '#/definitions/Person'
 

1. 格式錯誤問題

寫完後轉化成yaml 檔案 ，能消除一些格式錯誤的問題

提示錯誤 : can't resolve definitions/Person ...

2.關於自動補齊

不要使用自動補齊功能，他沒有IDEA的智慧，會引來不少麻煩 ：沒有公主命，偏有公主病，是你教的嗎，偶像 ?

你沒有自動改錯功能，卻有魔性的自動補全，顯然這個功能不完整，你可以自動補全剩餘的，但是不要自動補全全部的

所以建議全文手寫，不要按回車！請整段默寫並背誦

就比如我們已經定義了 ： Error 是什麼，那麼在我們想再一次使用Error的時候,我們寫下 Er 自動出現補全功能

我們的預期結果:

'#definitions/Error'
 

編輯器給我們的:

'#/definitions/'#/definitions/Error''

Pages 39

date:2020.07.20 21：15 .pm

3.格式對齊問題

關於格式 重要的元素強調 非重要的引數不需要

4.summary與description

總結和描述，其實差不多，仔細揣摩差別還是有的

5.關於幫助文件

其實過於冗餘了，有些寫了兩遍，有些不需要寫，就是沒有少內容，這點還是非常好的

2.書寫文件

1.問題1：

我要定義一個引用，想把它作為引數，但是parameters只允許很多的 - 欄位的引用 不允許一個欄位中有很多的屬性的型別引用,那我還要拆開是嗎?

顯然不是，顯然是配置好頭和屬性名 引用傳入的是一個json字串 返回的也是一個json字串

2020.07.21

2.問題2：

我後來發現對於Swagger編寫的文件 SpringBoot 能夠整合API用註解就可以完成整個鏈條的輸送：

邊搞配置檔案，邊JAVA code springboot 構建 註釋並匯出文件

但是SpringBoot短時期是未知的

3.關於鑑權問題：

OAuth2和token

看阮一峰：http://www.ruanyifeng.com/blog/2019/04/oauth_design.html

隨便說一句 ： SpringBoot Spring Mybatis Vue.js Angular.js React 這些東西只是讓開發更加快捷，更加便利，點到即可，主要攻關網路傳輸.整合物聯網，搞基礎建設。

2020.07.24

3.問題3：

我已經全都寫好了 ，然後手欠 convert into open api 全都變了 ....嗚嗚嗚 又花了一個點重構 .... 沒事思想還在 只要思想在，全丟了也沒事 ...

4.怎麼解決自定義definitions作為引數顯示不了的問題

1.格式設定

produces:
   - application/json
consumes:
   - application/json

2.雖然是自定義，需要schema

parameters:
	- name: user
      in: body
      schema:
      	$ref: '#/definitions/User'

需要傳遞引數 那麼頭上就要帶有引數名稱{param1}{param2}{param3}