Swagger Codegen 3 and Spring HATEOAS

Question

I'm taking my first swing at creating a RESTful API with OAS 3.0, Swagger Codegen, Spring MVC, and Spring HATEOAS. I want to use the OAS definition for documentation generation and server/client stub generation and use HATEOAS to create hyperlinks related resources.

I currently have my resources extending ResourceSupport and can add my links such that the responses have the _embedded and _links fields that I would expect. My issue is how to properly map the HATEOAS Resource to the model generated by Swagger codegen. My OAS definition matches the hal+json response, so the fields are identical in the swagger model and my HATEOAS Response .

Is there a way to easily map these? I'm also willing to accept that I am interpreting this incorrectly and that these frameworks don't really mesh together.

OAS example:

responses:
  200:
    description: ...
    content:
      application/hal+json:
        schema:
          $ref: '#/components/schemas/OasPersonResponse'

components:
  schemas:
    OasPersonResponse:
      type: object
          properties:
            firstName:
              type: string
            lastName:
              type: string
            _links:
              type: object
              properties:
                self:
                  type: object
                  properties:                  
                    href:
                    type: string

Resource example:

public class PersonResource extends ResourceSupport {
  private final Person person;

  public PersonResource(Person person) {
    this.person = person;
  }

  public String getFirstName() {
    return person.getFirstName();
  }

  public String getLastName() {
    return person.getLastName();
  }
}

Controller Example:

@Controller
public class PersonController implements PersonApi {

  @Override
  public ResponseEntity<OasPersonResponse> getPersonById(Integer personId) {
    Person person = someDb.getPerson(personId);
    PersonResource personResource = new PersonResource(person);

    personResource
      .add(linkTo(methodOn(PersonController.class)
        .getPersonById(personId))
      .withSelfRel();

    Resource<PersonResource> returnResource = 
      new Resource(personResource);

    return new ResponseEntity<>(returnResponse, HttpStatus.OK);
}

My issue is with the stub generated by swagger codegen expecting a return type of ResponseEntity<OasPersonResponse> but have a reference to a Resource<PersonResource> . Both OasPersonResponse and PersonResource represent the same data but the OasPersonResponse explicitly defines the _links object whereas the response with the PersonResource gets serialized to have the _links object.

Is there an easy way for me to convert the HATEOAS Resource to the model that was created by swagger codegen?

Thanks in advance for the help and guidance.

Answer 1

I'm currently working on a very similar project! Firstly, if you can, I'd recommend using the 1.0.0.RC1 version of spring-hateoas as it has some pretty major quality of life improvements over the 0.25.x release branch. Of major relevance is that using the EntityModel wrapper class is now the recommended practice, which means you can just leave the relations out of your base entity specification. (The downside is this reduces the immediate utility of the OpenAPI spec; I haven't quite figured out how to reconcile that yet.)

Secondly, I'm afraid there doesn't seem to be much existing work on the swagger-codegen side as far as supporting Spring HATEOAS is concerned; in fact, I keep running into annoying bugs with the plain Spring "language" generator.

So either we can write our own swagger-codegen generator for spring-hateoas, or just heavily customize some templates to get "close enough" (there's less of this needed when using the EntityModel wrapper rather than extending ResourceSupport ). I've gone with the latter approach so far, for what that's worth.