跳至主要内容

Living Documentation (OpenAPI)

作者資料

原始 MD by 智遠

Living Documentation (OpenAPI)

想傳達的要點​

減少寫文件導致增加程式碼冗餘的心裡負擔

沒有銀彈：人月神話​

無論中彈與否都是命中注定

沒有銀彈：軟體系統的天生特質

  • 複雜：系統結構的複雜、人的差異性
  • 配合：迎合不同時代的制度與系統界面
  • 易變：第三方不理解改變的成本
  • 隱匿：由於軟體不具備實體，缺乏明確使用工具的意圖。

程式設計的本質​

合適的資訊冗餘(S)是 程式設計的本質（M）

程式設計的本質(M) 是 建立在人與人之間理論的傳播橋樑（P）

-> S is P （規格的必要性證明）

冗餘的好壞​

合適的冗餘：

  • 減少時間的浪費
  • 進行最佳決策

基於以上概念上大有可為的作法​

  • 引用套件（基於優良且一致的文件體驗）
  • 需求的提煉與原型的快速製作 (OpenAPI Specification)
  • 漸進式開發
  • 資訊的冗餘化（Living Documentation）

體驗環節 Nest.js​

Swagger && Decorator(依賴注入)

npm i -g @nestjs/cli
nest new <project-name>

https://github.com/lowql/3-5_Demo.git

  • 11-swagger(X)
  • ts-decorator

Swagger ⌓‿⌓​

https://docs.nestjs.com/openapi/introduction

npm install --save @nestjs/swagger
//in main.ts

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('Cats example')
    .setDescription('The cats API description')
    .setVersion('1.0')
    .addTag('cats')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

  await app.listen(3000);
}
bootstrap();

Decorator ＠-＠​

它做了些什麼：

  • 技術層面實現文件的自動化
  • 增強程式碼的語意
  • 連結對應程式碼的位置
  • 符號對於系統外掛的隱喻