Всем привет! Я Ира — тимлид команды, которая занимается развитием и поддержкой публичного API hh.ru.

Несколько лет назад к нам пришли ребята из мобильной команды и сказали, что хотят документацию в OpenAPI формате. Для них это удобно, потому что можно генерировать DTO прямо из документации и не писать их руками. В то время у нас было выставлено около 100 URL, некоторые из них достаточно сложные. Например, в нашей документации у резюме есть три формата: нано, микро и полное. Каждый формат расширяет следующий, но теоретически могут быть и какие-то отличия, и это надо было изучать. В полном формате резюме более 30 полей и некоторые из них представлены в виде объектов. И такой URL у нас не один. Мы знали, что перевод документации на OpenAPI займет очень много времени, и в процессе мы, вероятно, столкнемся с трудностями (о них расскажу в статье), но при этом также понимали, что в долгосрочной перспективе мы получим от этого и много плюсов, поэтому решили попробовать. Что из этого получилось — читайте в нашем кейсе.