Swagger - как использовать swagger-codegen и построить проект в долгосрочной перспективе

Question

Проект Swagger замечателен, чтобы создавать на каждом языке легко клиентские и серверные приложения, но я не понимаю, как поддерживать или расширять существующий проект в надлежащим образом.

Я генерирую параметр языка сервера Java jaxrs-spec.

Я написал свой собственный Maven pom и используя swagger-codegen-maven-plugin, и теперь я могу сгенерировать модель или api напрямую с maven.

Я вижу, что каждый раз, когда я перестраиваю проект, API будет полностью переписан плагином swagger-codegen.

Мне нужно реализовать мою прикладную логику, и в данный момент я не видел другого способа, кроме как настроить созданные источники API. Итак, чтобы не потерять работу в каждой сборке, я мог бы настроить .swagger-codegen-ignore (и я сделал), но я отложил эту проблему.

Поскольку в первый раз я должен обновить swagger.json, единственный вариант, который у меня есть, - это регенерировать весь API и перезаписать мою работу. Хорошо, я мог бы использовать git и попытаться восстановить удаленную часть, но это действительно уродливое решение.

Итак, вопрос:

использование swagger-codegen (или Форс вообще) есть и шаблон, как, документированный способ, который позволит мне добавить поведение и/или расширить сгенерированный API, без перезаписи мой код?

Answer 1

Это зависит от выбранного вами языка/шаблонов, так как некоторые из них более гибкие, чем другие, но тот же принцип справедлив: Вы не должны добавлять дополнительную логику в сгенерированный код. К сожалению, просмотрев sample for jaxrs-spec, эти шаблоны выглядят не так хорошо, как те, что говорят, jaxrs-resteasy.

На данный момент, вы можете:

1. Переключение шаблонов в другой jaxrs
2. написать свои собственные шаблоны и использовать их вместо
3. Изменить/обновить чванства-Codegen шаблоны и зафиксировать их обратно ,

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

Для jaxrs-resteasy, вот что Codegen генерирует для метода GET /{username} (я удалил чванство аннотаций также ставит в):

@GET 
@Path("/{username}") 
@Produces({ "application/xml", "application/json" }) 
public Response getUserByName(@PathParam("username") String username,@Context SecurityContext securityContext) 
throws NotFoundException { 
    return delegate.getUserByName(username,securityContext); 
} 

Фактического метод только делегат на завод, который он получает примерно так:

private final UserApiService delegate = UserApiServiceFactory.getUserApi(); 

он может сделать это, потому что он также создает базовый класс для API для реализации:

public abstract class UserApiService { 
    // methods omitted... 
    public abstract Response getUserByName(String username, SecurityContext securityContext) throws NotFoundException; 
    // methods omitted... 
} 

Теперь, в не-сгенерированного кода, пользователь добавляет реализацию этого базового класса:

public class UserApiServiceImpl extends UserApiService { 
     // methods omitted... 
     @Override 
     public Response getUserByName(String username, SecurityContextsecurityContext) throws NotFoundException { 
      // do some magic! 
      return Response.ok().entity(new ApiResponseMessage(ApiResponseMessage.OK, "magic!")).build(); 
    } 
    // methods omitted... 
} 

И затем, пользователь добавляет завод в пакете, который Codegen ожидает, поэтому сгенерированный код можно получить выше реализации:

public class UserApiServiceFactory { 
    private final static UserApiService service = new UserApiServiceImpl(); 

    public static UserApiService getUserApi() { 
     return service; 
    } 
} 

Теперь код, который был сгенерирован точно знает, какая реализация UserApiService делегировать. На этом этапе весь серверный шаблонный блок отделен от логики приложения, что позволяет вам регенерировать API без перезаписывания вашей пользовательской логики.

_{В этом ответе предполагается, что образец для jaxrs-spec является точным примером того, что для этого параметра языка используется swagger-codegen. Иногда они устаревают.}