接著是我們討論的時間，請政委主持。

我們來看一下demo，這個是PTX的使用說明（如網站），這裡可以直接點下去，就會展開出類似剛剛的型態，這裡面會有針對API基本功能的描述、參數的描述，一樣有各個定義，甚至可以直接進行測試。你在完成之後，不用再作額外的轉譯動作。

我們目前有沒有採用這一個成果？有的，一個是交通部的PTX平台，他們非常厲害，他們規劃很久，整合了臺灣公共運輸的資訊。除了把他們的API通通提供一個符合OAS的文件之外，他們直接把它變成是線上的API說明，也就是在架設網站的時候，你完全不需要額外的功，就可以直接把這一些OAS文件變成網站API使用說明的一部分。

另外一個效益是，未來可以更容易去導入一些有關於Schema的資料標準，像API提供的資料，API是一個比較有彈性的開發方式，所以有時候的回傳值，別人在使用的時候，完全不知道哪一個欄位什麼東西，只要看到這一份API說明文件的人，就可以很容易理解每一個API欄位的值為何，這是它的效益。

就像我們達成一開始的目的，也就是讓API更容易使用、維護跟調整，也可以避免A機關跟B機關資料介接，特別去開發一個介接的方式，然後C機關跟A機關要資料，還要再特別開發一個方式，其實這一些當有API提供的時候，這些都可以降低一些重複開發的成本。

另外，針對各個機關已經有建置的API，其實基本上是不需要進行調整，因為我們的規範要求是說明文件的程式化，應該說機器可讀化。

（簡報第26頁）很快來到小結，其實有一個原則，也就是什麼樣的東西會需要適用這樣的規範？像建置、維護的API就適用這一個規範。再者，重點API的說明文件是需要符合OAS的標準。

（簡報第25頁）在這一次規範的修正裡面，還有一項比較新的是API Discovery，這一項的功能是當各機關的系統可能有一部分API是可以提供外界直接查詢的，我們要如何提高這一些API的可識別程度？可以在這一個系統的目錄下去加APIs.json的文件，裡面可以加入這樣的敘述，這樣的敘述，別人就可以很容易得知這個網站裡面有提供哪一些API服務，就可以跟前面的OAS文件搭配，就可以知道你們提供的API，除了可以知道哪一些之外，也知道應該如何使用它。

（簡報第23頁）API的版本描述，這個也是舊的，很單純在API的後面加上一個版本，然後後面還有一些名稱規範。

（簡報第21頁）接著是規範準則第二項，有關於RESTful API的立法規則，這個是舊規範，但是很簡單；什麼是RESTful API？其實就是一種API風格的設計，我想資訊人員應該都不至於太陌生，純粹是很簡單的型態、範例。

因為我們規範當中所描述的OAS部分是根據OAS3.0的部分描述，近期可能會做正式的釋出，目前還沒有正式工具可以使用，但已經一些第三方的工具可以參考，我們可以視自己的專案需求，決定採用之前或之後的版本，其實都有工具可以使用。

（簡報第19頁）這個同時是測試兼呈現的網站。

也就是API裡面，像這個是資料集編號清單的功能（如網站），像裡面有一些回傳址的一些欄位或參數的描述，同時也可以進行測試，而測試的部分就可以直接輸入，像是正在呼叫這一些API一樣，可以丟入你所要的參數。

除了檢測通過以後，還有一個很重要的是，因為畢竟是一份API的說明文件，是否符合各機關的需求，還要由各機關去看我們這邊所提供的API功能是不是跟這一份說明文件是吻合的；如果既符合格式的測試，也符合機關專案需求的話，我們就會視為通過驗證。

那時在跟其他部會討論時，有一些部會很擔心的一點是，如果要請廠商或者是自己撰寫出一份API說明文件，要如何驗證這一份文件是否是合乎標準的？其實這個大家不用擔心，應該是說OAI組織本身就有提供官方的驗證工具，可以很簡單把撰寫出來的YAML或者JSON檔丟上網站，就會有驗證的結果，我們稍候都會有demo。

基本上只要follow我們提供的一個規範附件OAS標準，其實只要有一點程式底子的人都可以寫出這樣的文件。

剛剛有一頁看起來很像程式碼那一頁，其實就是基於更物件，也就是OpenAPI Object，裡面每一個物件，其中的欄位跟屬性，有一點像物件繼承的概念，有一點像物件所構成的一份說明文件。

（簡報第16頁）OAS文件基本上是由單一的檔案製成，也就是提供一個系統服務，裡面可能有七支、十支API，你可以在同一份文件裡面撰寫，而這份文件，我們會建議是JSON或YAML格式來呈現；這個部分大家不用緊張，因為我們規範後面都有提供範例、原文。

符合OAS標準的說明文件，因為名字有一點長，所以我接下來就簡稱OAS文件，接下來會針對它的重點來說明。

（簡報第13頁）其實規範準則的部分，大部分是沿用我們之前一個政府資料開放平台適用的叫做「共通性資料存取應用程式介面規範」，其實原本的適用範圍比較僅限於資料開放的範疇下，但是因為現在的範圍是整個擴大到一般適用的API，這邊會有輕便性、標準化都是原本的內容，而共通性的部分就是加註這一次的OAI的OAS標準。

也就是這一個規範的修正，並不是要求大家API要如何訂定，而是API的說明文件要符合OAS標準。

（簡報第11頁）我們剛剛講的右邊是傳統式的API說明文件，左邊是能夠符合OAS標準之後，透過工具轉化出來的結果，你覺得哪一個比較好用？我想大家應該都有答案吧！這個也是為什麼這一次共通性規範會做這樣的修訂，這個是大家希望能夠針對API的部分，去提供符合OAS標準的API說明文件。

什麼是符合OAS標準的說明文件？其實看起來就像是一串程式碼一樣，有一個完整的架構。因為這邊是一個說明會的性質，所以暫時不贅述程式碼的部分，剛剛那個程式碼可以透過工具，變成具親和力，也就是非常容易理解的UI介面，而這一個UI介面不只是讓人容易理解這一份說明文件，這個範例是政府資料開放平台的介接規範，裡面可能就是簡單的五支API，不只看到API，還有看到介面下進行一些參數的操作，也就是這一份說明文件是可以直接參與互動的，而不是一份靜態的文件而已。

（簡報第8頁）甚至有一些API的說明文件都沒有，我相信這個應該各位長官先進都知道這一種情況。

用這樣的方式提供的話，其實對於開發者而言，也要重新看很長的文件才能理解這一個API要怎麼樣使用，就各個參數、功能什麼樣的型態存取。

什麼叫做「API說明文件」，我相信這邊大部分都是資訊同仁，所以大家對這個應該都不會太陌生，也就是裡面充斥著很難製作的一些合併儲存格拼湊出來的Word文件，然後再轉成PDF。

重點在於API開發應該提供OAS標準的說明文件。

只要提供API說明文件的話，就能夠具有一定的共通性，讓API能夠透過某種方式都能夠理解API是什麼用途。我們在推動規範的時候，並不會受到限制，也就是API可能只是機關內部的資料介接，或者是有一些特別的存取限制什麼的，這個都不會影響規範的適用。按

我剛剛只有講到API的部分而已，其實跟大家想像的Open Data有一點脫鉤的，就是說並不是只適用於Open Data的範疇，而是所有採用API進行應用的範圍，通通都適用。

實質上的目的是，可以藉由一個一致性的描述方式，讓大家把API的說明文件提供機器可讀的標準格式，就藉由這一個方式來達成前面所說的目的。

簡單是從目的、應用反應及推動的規範準則。目的講白了非常簡單，也就是希望API更容易被使用，能夠更容易被調整或者是維護。先說明一下API在機關裡面常常拿來作什麼，可能被拿來作一些資料存取、資料交換之用，常常會發生一些狀況，也就是有些廠商可能開發出一個API，什麼東西都沒有留下，之後可能因為某些原因而沒有繼續得標或維護，而這一個API的功能就這樣消失。所以我們希望藉由共通性規範API的修訂，讓API的功能更容易被知道與使用。

        （簡報第4頁）這個是規範當中比較正式的文字，也就是為了擴大政府資訊服務效益，並且在保有各機關的API開發系統的彈性上，我們希望大家能夠follow OAI組織所訂出來的OAS（OpenAPI Specification）的標準，之前大家可能會聽到以OPI的規範，其實指的是這一個OAS的標準。

我先說明一下什麼是應用程式介面，這個名字有一點拗口，所以我之後會用「API」來簡稱，也就是應用程式介面。

我是國家發展委員會的承辦人，接下來就由我為各位介紹一下共通性應用程式規範的草案。

先請主席致詞。

今天討論的議題是，有關於OpenAPI的spec，也就是中文版本的適用性，還有字典檔的中英文對照，還有提到OData及GraphQL的部分有沒有需要納入這一個規範當中，大概會針對這三方面進行調整。簡單介紹到這邊。

工作期程預計，在3月有請團隊完成初稿，希望在5月份的時候，能夠公告最終的版本，今天是3月最後的階段。

難道這樣就是Open API嗎？已經劃掉了，經唐政委大大的解釋，Open API其實應該是從Web API加Schema，變成Common API之後，再搭配Open Data而形成的Open API，如果說明不清楚，要再麻煩政委大大補充一下。

我們如果導入Data Schema的話，使用API的人會更清楚API裡面的欄位、型態及定義是什麼。

昨天請教唐政委，經唐政委開示之後，我們把這個認知稍微修正一下，也就是會變成Web API加Data Schema的概念，原先的Swagger裡面，其實是有針對各個資料欄位作一些更嚴謹的要求，是對一個資料欄位描述，這應該算是在Schema的概念，那時以為這樣就是Open API了嗎？Web API其實跟Web Service不太一樣，也就是Web API純粹是在資料存取上的方式，包含的方式可能包含舊有的規範，以及大部分採用新Open API的型態。

Swagger是一個OAI組織訂出來的規格，最主要是讓API產生一份說明文件，然後這一份說明文件，透過產生工具，產生更容易使用的介面。

我們一開始接到這個任務的時候，想要瞭解什麼是一個Open API，原本很傻、很天真以為純粹是RESTful API加上Swagger的規範。什麼是RESTful API？我想這邊很多專家，所以我簡單帶過，RESTful API是一個彈性設計的樣式，而且並不是標準。

大家好，我是國發會資管處的鄭立源，也就是目前OpenAPI的承辦科，接下來由我為各位簡報OpenAPI的目前狀況。