Введение
В современном мире веб-разработки безопасность типов играет решающую роль в создании надежных и удобных в сопровождении приложений. TypeScript, надмножество JavaScript со статическими типами, стал популярным языком для разработчиков, которые хотят писать типобезопасный код. OpenAPI, с другой стороны, является широко распространенным форматом описания API, который помогает вам проектировать, создавать, документировать и тестировать ваши API.
В этом сообщении блога мы расскажем вам, как создавать безопасные для типов API с помощью TypeScript и OpenAPI. Мы продемонстрируем это, создав простой REST API для управления коллекцией статей.
Шаг 1: Настройте проект
Для начала создайте новую папку для своего проекта и инициализируйте ее с помощью npm:
mkdir type-safe-api cd type-safe-api npm init -y
Далее устанавливаем необходимые зависимости:
npm install --save express npm install --save-dev typescript @types/express ts-node
Создайте файл tsconfig.json в корне проекта:
{
"compilerOptions": {
"target": "es6",
"module": "commonjs",
"outDir": "./dist",
"strict": true,
"esModuleInterop": true
},
"include": ["src/**/*.ts"],
"exclude": ["node_modules"]
}
Шаг 2: Определите спецификацию OpenAPI
Создайте новую папку с именем openapi и файл с именем spec.yml внутри нее. Определите свой API, используя спецификацию OpenAPI:
openapi: 3.0.0
info:
title: Article API
version: 1.0.0
paths:
/articles:
get:
summary: Get all articles
responses:
'200':
description: A list of articles
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Article'
components:
schemas:
Article:
type: object
properties:
id:
type: string
title:
type: string
content:
type: string
required:
- id
- title
- content
Шаг 3. Сгенерируйте типы TypeScript из спецификации OpenAPI.
Установите пакет openapi-typescript для создания типов TypeScript из спецификации OpenAPI:
npm install --save-dev openapi-typescript
Добавьте скрипт в свой package.json для генерации типов:
"scripts": {
"generate-types": "openapi-typescript openapi/spec.yml --output src/types/api.ts"
}
Запустите скрипт для генерации типов:
npm run generate-types
Шаг 4: Реализуйте API с безопасностью типов
Создайте новую папку с именем src и файл с именем index.ts внутри нее. Импортируйте необходимые модули и сгенерированные типы:
import express from "express";
import { Article } from "./types/api";
Создайте простое хранилище статей в памяти:
const articles: Article[] = [];
Определите маршрут для получения всех статей:
const app = express();
app.use(express.json());
app.get("/articles", (req, res) => {
res.json(articles);
});
Наконец, запустите сервер:
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
console.log(`Server is running on port ${PORT}`);
});
Теперь у вас есть типобезопасный API с TypeScript и OpenAPI. По мере роста вашего API вы можете легко добавлять дополнительные конечные точки, обеспечивая безопасность типов на каждом этапе.
Шаг 5: Обновите спецификацию OpenAPI
Добавьте конечную точку post к пути /articles в вашем spec.yml:
post:
summary: Create a new article
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ArticleInput'
responses:
'201':
description: The created article
content:
application/json:
schema:
$ref: '#/components/schemas/Article'
И определите схему ArticleInput в разделе components:
ArticleInput:
type: object
properties:
title:
type: string
content:
type: string
required:
- title
- content
Шаг 6: Восстановите типы TypeScript
Запустите скрипт для повторного создания типов TypeScript на основе обновленной спецификации OpenAPI:
npm run generate-types
Шаг 7: Реализуйте конечную точку создания статьи
Обновите файл index.ts, чтобы включить в него новый тип ArticleInput и реализовать конечную точку создания статьи:
import { v4 as uuidv4 } from "uuid";
import { Article, ArticleInput } from "./types/api";
// ...
app.post("/articles", (req, res) => {
const articleInput: ArticleInput = req.body;
const newArticle: Article = { ...articleInput, id: uuidv4() };
articles.push(newArticle);
res.status(201).json(newArticle);
});
Теперь у вашего API есть конечные точки get и post для управления статьями, все они реализованы с безопасностью типов с использованием TypeScript и OpenAPI. Продолжая разработку своего API, вы можете воспользоваться преимуществами функций обеспечения безопасности типов, чтобы заблаговременно обнаруживать потенциальные ошибки, оптимизировать процесс разработки и улучшить общее качество кода.
Заключение
TypeScript и OpenAPI вместе представляют собой мощную комбинацию для создания типобезопасных API. Используя эти инструменты, вы можете создавать надежные и удобные в сопровождении API-интерфейсы с улучшенными возможностями для разработчиков и качеством кода. Этот пост в блоге служит отправной точкой для создания типобезопасных API, и вы можете расширить его в соответствии с требованиями вашего конкретного приложения.
