Can OpenAPI integrate HATEOAS in a useful way?

Viewed 753

Is it possible to describe a HATEOAS REST API with OpenAPI?

When I describe the API in HAL Format I would need to define three schemas for it (one for Request Payloads, one for Collection Resource and one for Item Resource). For Example:

components:
  schemas:
    Link:
      type: object
      properties:
        href:
          type: string
        hreflang:
          type: string
        title:
          type: string
        type:
          type: string
        deprecation:
          type: string
        profile:
          type: string
        name:
          type: string
        templated:
          type: boolean
    Links:
      type: object
      discriminator:
        propertyName: _links
      properties:
        _links:
          type: object
          additionalProperties:
            type: string
            $ref: "#/components/schemas/Link"
    CollectionModel:
      type: object
      discriminator:
        propertyName: _embedded
      properties:
        _embedded:
          type: object
        _links:
          type: object
          properties:
            self:
              type: string
            profile:
              type: string
            search:
              type: string
    CollectionModel_Foo:
      type: object
      allOf:
        - $ref: "#/components/schemas/CollectionModel"
      properties:
        _embedded:
          type: object
          properties:
            projects:
              type: array
              items:
                $ref: "#/components/schemas/EntityModel_Foo"
    EntityModel_Foo:
      type: object
      allOf:
        - $ref: "#/components/schemas/Foo"
        - $ref: "#/components/schemas/Links"
    Foo:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        bar:
          type: string

I don't find that very useful because that complicates the specification and since when generating a client based on that schema using OpenAPI Generator the client does not pay attention to HATEOAS and simply requests the resources. So in this context it is useless.

I thought about implementing JSON:API but sadly the full JSON Schema is only supported in the current OpenAPI 3.1 draft.

All in all I can't find a proper way to integrate OpenAPI in a HATEOAS API.

0 Answers
Related