База технических писателей

Версия API: 1.0.0

Описание API:

API для работы с базой данных о технических писателях и их навыками.

API позволяет получать:

список технических писателей,
список навыков каждого из них,
информацию о конкретном техническом писателе по идентификатору.

Также здесь можно получать информацию о навыках, добавлять новых технических писателей, редактировать сведения об имеющихся в базе техписах.

В версии API 1.0.0 реализовано добавление нового навыка, редактирование навыка, удаление навыка.

Список серверов:

Dev-сервер: https://dev.tw_api.com/v1

Prod-сервер: https://tw_api.com/v1

Список конечных точек

POST /techwriters/{test_request_body}/with_body_inline

Метод для тестирования рендеринга тела запроса

Метод для тестирования рендеринга тела запроса с телом, описанным прямо в методе

Параметры:

№	Параметр	Тип, формат	Расположение	Обязательный	Описание
1	test_request_body	`integer`	path	Да	test_request_body

Тело запроса

Описание объекта: Данные технического писателя (тело описано прямо в методе)

true

firstName: string

Имя технического писателя

Пример значения: Вася

secondName: string

Фамилия технического писателя

Пример значения: Пупкин

patronymic: string

Отчество технического писателя. Необязательное поле

Пример значения: Иванович

experience: integer

Опыт работы (в месяцах)

Пример значения: 12

phoneNumber: string

Номер телефона для связи

Пример значения: 71234567890

email: string

Адрес электронной почты технического писателя

Пример значения: pupkin@mail.pup

skill: object

id: integer

Идентификатор навыка

Пример значения: 25

skillName: string

Название навыка

Пример значения: Ручное документирование API

skillDescription: string

Описание навыка

Пример значения: Создание документации на API, тестирование, создание описаний вручную

alias: string

Алиас навыка

Пример значения: manualApiDocs

POST /techwriters/{test_request_body}/with_body_link

Метод для тестирования рендеринга тела запроса

Метод для тестирования рендеринга тела запроса с вложенным полем-объектом по ссылке

Параметры:

№	Параметр	Тип, формат	Расположение	Обязательный	Описание
1	test_request_body	`integer`	path	Да	test_request_body

Тело запроса

Описание объекта: Данные технического писателя

true

firstName: string

Имя технического писателя

Пример значения: Вася

secondName: string

Фамилия технического писателя

Пример значения: Пупкин

patronymic: string

Отчество технического писателя. Необязательное поле

Пример значения: Иванович

experience: integer

Опыт работы (в месяцах)

Пример значения: 12

phoneNumber: string

Номер телефона для связи

Пример значения: 71234567890

email: string

Адрес электронной почты технического писателя

Пример значения: pupkin@mail.pup

skill: object

id: integer

Идентификатор навыка

Пример значения: 25

skillName: string

Название навыка

Пример значения: Ручное документирование API

skillDescription: string

Описание навыка

Пример значения: Создание документации на API, тестирование, создание описаний вручную

alias: string

Алиас навыка

Пример значения: manualApiDocs

GET /techwriters

Получение списка технических писателей

Метод возвращает список технических писателей из базы.

Параметры:

№	Параметр	Тип, формат	Расположение	Обязательный	Описание
1	limit	`integer`	query	Нет	Количество технических писателей в выдаче (для пагинации). Значение по умолчанию `20`

POST /techwriters

Добавление технического писателя в базу

Метод добавляет нового технического писателя в базу

Тело запроса

Описание объекта: Данные технического писателя

true

firstName: string

Имя технического писателя

Пример значения: Вася

secondName: string

Фамилия технического писателя

Пример значения: Пупкин

patronymic: string

Отчество технического писателя. Необязательное поле

Пример значения: Иванович

experience: integer

Опыт работы (в месяцах)

Пример значения: 12

phoneNumber: string

Номер телефона для связи

Пример значения: 71234567890

email: string

Адрес электронной почты технического писателя

Пример значения: pupkin@mail.pup

skills: array

Список навыков (массив идентификаторов навыков)

Пример значения: 123

GET /techwriters/{techwriterId}

Получение информации о техническом писателе по идентификатору

Метод возвращает информацию о техническом писателе по его идентификатору

Параметры:

№	Параметр	Тип, формат	Расположение	Обязательный	Описание
1	techwriterId	`integer`	path	Да	Идентификатор технического писателя, о котором нужно получить информацию

PATCH /techwriters/{techwriterId}

Редактирование сведений о техническом писателе

Метод изменяет сведения о техническом писателе. Метод изменяет сведения частично: можно передать только имя, фамилию, отчество, опыт, номер телефона, адрес электронной почты или идентификатор навыка. Обязательно должен быть передан хотя бы один параметр

Параметры:

№	Параметр	Тип, формат	Расположение	Обязательный	Описание
1	techwriterId	`integer`	path	Да	Идентификатор технического писателя, сведения о которым нужно изменить

Тело запроса

Описание объекта: Изменяемые сведения о техническом писателе

true

firstName: string

Имя технического писателя

Пример значения: Вася

secondName: string

Фамилия технического писателя

Пример значения: Пупкин

patronymic: string

Отчество технического писателя. Необязательное поле

Пример значения: Иванович

experience: integer

Опыт работы (в месяцах)

Пример значения: 12

phoneNumber: string

Номер телефона для связи

Пример значения: 71234567890

email: string

Адрес электронной почты технического писателя

Пример значения: pupkin@mail.pup

skills: array

Список навыков (массив идентификаторов навыков)

Пример значения: 123

DELETE /techwriters/{techwriterId}

Удаление технического писателя из базы

Метод для удаления технического писателя из базы по его идентификатору

Параметры:

№	Параметр	Тип, формат	Расположение	Обязательный	Описание
1	techwriterId	`integer`	path	Да	Идентификатор технического писателя, которого нужно удалить из базы

GET /techwriters/{techwriterId}/skills/{skillId}

Получение информации о конкретном навыке конкретного технического писателя

Метод возвращает информацию о конкретном навыке конкретного технического писателя. Возвращается общая информация плюс опыт и подтверждающий документ для конкретного технического писателя

Параметры:

№	Параметр	Тип, формат	Расположение	Обязательный	Описание
1	techwriterId	`integer`	path	Да	Идентификатор технического писателя, о навыке которого нужно получить информацию
2	skillId	`integer` , `int64`	path	Да	Идентификатор навыка конкретного технического писателя, о котором нужно получить информацию

POST /techwriters/{techwriterId}/skills/{skillId}

Добавление навыка для определенного технического писателя

Метод добавляет конкретный навык для определенного технического писателя

Параметры:

№	Параметр	Тип, формат	Расположение	Обязательный	Описание
1	techwriterId	`integer` , `int64`	path	Да	Идентификатор технического писателя, которому добавляется навык
2	skillId	`integer` , `int64`	path	Да	Идентификатор навыка

Тело запроса

Описание объекта: Подтверждение навыка конкретного техписателя

true

confirmingDocument: string

Подтверждающий документ

Пример значения: mydocuments.com/API.pdf

linksExamples: array

Ссылки на примеры работ

GET /skills

Получение информации о доступных в системе навыках

Метод возвращает информацию обо всех доступных в системе навыках

Параметры:

№	Параметр	Тип, формат	Расположение	Обязательный	Описание
1	limit	`integer`	query	Нет	Количество навыков в выдаче (для пагинации). Значение по умолчанию `20`

POST /skills

Добавление навыка в базу

Метод добавляет новый навык в базу

Тело запроса

Описание объекта: Описание навыка

true

skillName: string

Название навыка

Пример значения: Ручное документирование API

skillDescription: string

Описание навыка

Пример значения: Создание документации на API, тестирование, создание описаний вручную

alias: string

Алиас навыка (на английском языке в camelCase)

Пример значения: manualApiDocs

GET /skills/{skillId}

Получение информации о навыке по идентификатору

Метод возвращает информацию о навыке по его идентификатору

Параметры:

№	Параметр	Тип, формат	Расположение	Обязательный	Описание
1	skillId	`integer`	path	Да	Идентификатор навыка, о котором нужно получить информацию

PATCH /skills/{skillId}

Редактирование навыка

Метод изменяет описание навыка. Метод изменяет навык частично: можно передать только название, описание или алиас для изменения. Обязательно должен быть передан хотя бы один параметр

Параметры:

№	Параметр	Тип, формат	Расположение	Обязательный	Описание
1	skillId	`integer`	path	Да	Идентификатор навыка, который нужно изменить

Тело запроса

Описание объекта: Изменяемые свойства навыка

true

skillName: string

Название навыка

Пример значения: Ручное документирование API

skillDescription: string

Описание навыка

Пример значения: Создание документации на API, тестирование, создание описаний вручную

alias: string

Алиас навыка (на английском языке в camelCase)

Пример значения: manualApiDocs

DELETE /skills/{skillId}

Удаление навыка из базы

Метод удаляет навык из базы по его идентификатору

Параметры:

№	Параметр	Тип, формат	Расположение	Обязательный	Описание
1	skillId	`integer`	path	Да	Идентификатор навыка, который нужно удалить

Компоненты

Schemas

NewSkill

object

{"skillName"=>{"type"=>"string", "description"=>"Название навыка", "example"=>"Ручное документирование API"}, "skillDescription"=>{"type"=>"string", "description"=>"Описание навыка", "example"=>"Создание документации на API, тестирование, создание описаний вручную"}, "alias"=>{"type"=>"string", "description"=>"Алиас навыка (на английском языке в camelCase)", "example"=>"manualApiDocs"}}

UpdSkill

object

NewTechwriter

object

{"firstName"=>{"type"=>"string", "description"=>"Имя технического писателя", "example"=>"Вася"}, "secondName"=>{"type"=>"string", "description"=>"Фамилия технического писателя", "example"=>"Пупкин"}, "patronymic"=>{"type"=>"string", "description"=>"Отчество технического писателя. Необязательное поле", "example"=>"Иванович"}, "experience"=>{"type"=>"integer", "format"=>"int64", "description"=>"Опыт работы (в месяцах)", "example"=>12}, "phoneNumber"=>{"type"=>"string", "format"=>"phone", "description"=>"Номер телефона для связи", "example"=>71234567890}, "email"=>{"type"=>"string", "format"=>"email", "description"=>"Адрес электронной почты технического писателя", "example"=>"pupkin@mail.pup"}, "skills"=>{"type"=>"array", "description"=>"Список навыков (массив идентификаторов навыков)", "items"=>{"type"=>"integer", "format"=>"int64", "example"=>1}, "example"=>[1, 2, 3]}}

TechwriterTestBody

object

Techwriter

object

{"id"=>{"type"=>"integer", "format"=>"int64", "description"=>"Идентификатор технического писателя", "example"=>123}, "firstName"=>{"type"=>"string", "description"=>"Имя технического писателя", "example"=>"Вася"}, "secondName"=>{"type"=>"string", "description"=>"Фамилия технического писателя", "example"=>"Пупкин"}, "patronymic"=>{"type"=>"string", "description"=>"Отчество технического писателя. Необязательное поле", "example"=>"Иванович"}, "experience"=>{"type"=>"integer", "format"=>"int64", "description"=>"Опыт работы (в месяцах)", "example"=>12}, "phoneNumber"=>{"type"=>"string", "format"=>"phone", "description"=>"Номер телефона для связи", "example"=>71234567890}, "email"=>{"type"=>"string", "format"=>"email", "description"=>"Адрес электронной почты технического писателя", "example"=>"pupkin@mail.pup"}, "skills"=>{"type"=>"array", "description"=>"Список навыков (массив идентификаторов навыков)", "items"=>{"type"=>"integer", "format"=>"int64", "example"=>1}, "example"=>[1, 2, 3]}}

UpdTechwriter

object

Skill

object

{"id"=>{"type"=>"integer", "format"=>"int64", "description"=>"Идентификатор навыка", "example"=>25}, "skillName"=>{"type"=>"string", "description"=>"Название навыка", "example"=>"Ручное документирование API"}, "skillDescription"=>{"type"=>"string", "description"=>"Описание навыка", "example"=>"Создание документации на API, тестирование, создание описаний вручную"}, "alias"=>{"type"=>"string", "description"=>"Алиас навыка", "example"=>"manualApiDocs"}}

TechwriterSkill

object

{"techwriterId"=>{"type"=>"integer", "format"=>"int64", "description"=>"Идентификатор технического писателя", "example"=>123}, "skillCommonInfo"=>{"$ref"=>"#/components/schemas/Skill"}, "confirmingDocument"=>{"type"=>"string", "description"=>"Подтверждающий документ", "example"=>"mydocuments.com/API.pdf"}, "linksExamples"=>{"type"=>"array", "description"=>"Ссылки на примеры работ", "items"=>{"type"=>"string", "example"=>["myexamples.com/example_1", "myapidocs.com/exampleApiDoc.png"]}}}

TechwriterSkillInfo

object

{"confirmingDocument"=>{"type"=>"string", "description"=>"Подтверждающий документ", "example"=>"mydocuments.com/API.pdf"}, "linksExamples"=>{"type"=>"array", "description"=>"Ссылки на примеры работ", "items"=>{"type"=>"string", "example"=>["myexamples.com/example_1", "myapidocs.com/exampleApiDoc.png"]}}}

Parameters

{"SkillId"=>{"name"=>"skillId", "in"=>"path", "description"=>"Идентификатор навыка конкретного технического писателя, о котором нужно получить информацию", "required"=>true, "schema"=>{"type"=>"integer", "format"=>"int64", "example"=>25}}}