Тратьте свое время на действительно важные дела. Например, пишет ваш документ API. Пусть клиент API будет создан с душевным спокойствием.
Жизнь перед смертью.
Сила перед слабостью.
Путешествие перед целью. - Брэндон Сандерсон
Мне нравится Архив штормового света. Хотя я надеюсь, что мистер Сандерсон доделает его поскорее. Но я думаю, ожидание - тоже часть удовольствия. Тем не менее, эта цитата имеет некоторое сходство с тем, о чем я собираюсь говорить, с небольшими изменениями.
API перед фронтенд-разработкой.
Я был там, когда фронтенду приходилось работать с API без какой-либо документации. Вам придется кодировать (или тратить свое время) на интерфейс запроса и ответа. И вызовите конечную точку API с помощью jQuery или $ q. У вас может возникнуть соблазн пропустить объявление объекта передачи, но вы пожалеете об этом, когда кто-то из вашей серверной команды изменит определения API.
С помощью чванства дела обстоят намного проще.
Все конечные точки будут сгенерированы как службы, и все они возвращают Observable с соответствующим типом!
1. Создайте угловую библиотеку
Я пробовал использовать небиблиотечный подход, чтобы сгенерировать клиент API в основной папке src. Я должен сказать, это довольно грязно. Поскольку сгенерированные коды смешиваются с другими, вы должны будете игнорировать их по каталогу с помощью git. Что еще хуже, вам придется заниматься удалением. По мере развития API вы будете отказываться от моделей и переименовывать API чаще, чем вы думаете. Повторное создание нового API может заменить API с тем же именем, но не удалит автоматически API с разными именами.
Используйте подход с использованием библиотеки angular, это так же просто, как удалить папку библиотеки src прямо перед запуском swagger codegen, чтобы получить чистую сборку.
ng generate library foo-swagger-client
2. Приведите в порядок библиотеку angular.
Angular CLI сгенерирует за вас проект библиотеки. Вы должны найти его в каталоге projects / foo-swagger-client. Он также генерирует компонент и службу, которые мало полезны в нашем сценарии. Давайте удалим всю папку src. В нашем случае projects/foo-swagger-client/src.
3. Создайте клиент API.
Предположим, вы подготовили документ со спецификацией API. Сейчас мы воспользуемся swagger-codegen для создания клиента API. Если вы используете Angular 7, прочтите другую мою статью, чтобы узнать, как это сделать.
Здесь я буду использовать swagger-codegen 2.4.0 через докер.
rm -rf projects/foo-swagger-client/src
mkdir -p tmp
SPECFILE=tmp/spec.json
wget --quiet --no-check-certificate $SPECURL -O $SPECFILE
docker run --rm --net=host -u="$(id -u)" -v ${PWD}:/local swaggerapi/swagger-codegen-cli:2.4.0 generate \
-i /local/$SPECFILE \
-l typescript-angular \
-o /local/projects/foo-swagger-client/src \
--additional-properties ngVersion=7.2.0
Команды используют wget для загрузки файла спецификации из $ SPECURL. Это должно указывать на ваш файл спецификации. Я использую wget, чтобы обойти проблему с самозаверяющим сертификатом, чтобы сценарий работал во всех средах.
Теперь давайте взглянем на вашу библиотеку foo-swagger-client.
api содержит все службы, которыми вы будете пользоваться. Все конечные точки были сгенерированы как служба, вводимая зависимостями, и все они возвращают Observable с соответствующим типом!
4. Обновите entryFile.
Проект библиотеки Angular почти завершен, осталось сделать еще один шаг. Нам нужно указать Angular точку входа в эту библиотеку. Swagger сгенерировал для нас входной файл index.ts, нам просто нужно сообщить об этом Angular. Измените его в файле projects/foo-swagger-client/ng-package.json.
Теперь мы можем построить проект библиотеки.
ng build foo-swagger-client
5. Используйте клиент API.
Сначала добавьте его в свой AppModule.
import {ApiModule} from 'foo-swagger-client';
@NgModule({
declarations: [
AppComponent
],
imports: [
...
ApiModule.forRoot(IdentityService.getApiConfiguration),
...
})
export class AppModule {
}
IdentityService.getApiConfiguration () - статический метод, с помощью которого вы можете предоставить конфигурацию API. Обычно в этом методе требуется заполнить токен аутентификации.
Обратите внимание, что для импорта используется «foo-swagger-client», а не относительный путь. Библиотека предоставляется как модуль npm. Это особенно верно в режиме разработки, где ng serve автоматически выбирает библиотеку. Это достигается за счет конфигурации путей в tsconfig.json в корневой папке проекта. Обратите внимание: трюк с путями работает только для компилятора машинописного текста. Когда я попытался использовать его в своем проекте Angular Universal, сборка просто не удалась, и мне пришлось использовать npm link, чтобы исправить это.
Я не пробовал, но думаю, что импорт по относительному пути тоже должен работать. Однако использование имени модуля библиотеки даст вам больше гибкости в будущем. Возможно, вы когда-нибудь захотите опубликовать свою библиотеку на npm.
Заключение
Я рекомендую всем попробовать чванство, это определенно стоит потраченного времени.
Проверка типов - это благо Angular (на самом деле Typescript). Не бойтесь улучшать свой API. Просто используйте 10 секунд, чтобы повторно сгенерировать клиент API, и увидите, как компилятор жалуется. Скоро вы узнаете, где провести рефакторинг своих кодов!
Я напишу еще одну статью о том, как создать спецификацию из приложения игрового фреймворка. Это не связано с Angular, но вернитесь позже, если вам интересно.
Подробнее о #Swagger
Вы узнали что-то новое? Если да, пожалуйста:
↓ кнопка хлопка 👏 внизу, чтобы это увидело больше людей
