Skip to content
GitLab
Projects Groups Snippets
  • /
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in / Register
  • O openapi-generator
  • Project information
    • Project information
    • Activity
    • Labels
    • Members
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
  • Issues 3,476
    • Issues 3,476
    • List
    • Boards
    • Service Desk
    • Milestones
  • Merge requests 402
    • Merge requests 402
  • CI/CD
    • CI/CD
    • Pipelines
    • Jobs
    • Schedules
  • Deployments
    • Deployments
    • Environments
    • Releases
  • Packages and registries
    • Packages and registries
    • Package Registry
    • Infrastructure Registry
  • Monitor
    • Monitor
    • Incidents
  • Analytics
    • Analytics
    • Value stream
    • CI/CD
    • Repository
  • Wiki
    • Wiki
  • Snippets
    • Snippets
  • Activity
  • Graph
  • Create a new issue
  • Jobs
  • Commits
  • Issue Boards
Collapse sidebar
  • OpenAPI Tools
  • openapi-generator
  • Issues
  • #1901
Closed
Open
Issue created Jan 12, 2019 by Jim Schubert@jimschubertContributor

[REQ] Support OpenAPI 3.x links

Is your feature request related to a problem? Please describe.

Currently, openapi-generator doesn't support OpenAPI Specification's links.

Expand for full sample spec
openapi: 3.0.0
info: 
  title: Link Example
  version: 1.0.0
paths: 
  /2.0/users/{username}: 
    get: 
      operationId: getUserByName
      parameters: 
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses: 
        '200':
          description: The User
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/user'
          links:
            userRepositories:
              $ref: '#/components/links/UserRepositories'
  /2.0/repositories/{username}:
    get:
      operationId: getRepositoriesByOwner
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: repositories owned by the supplied user
          content: 
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/repository'
          links:
            userRepository:
              $ref: '#/components/links/UserRepository'
  /2.0/repositories/{username}/{slug}: 
    get: 
      operationId: getRepository
      parameters: 
        - name: username
          in: path
          required: true
          schema:
            type: string
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses: 
        '200':
          description: The repository
          content:
              application/json: 
                schema: 
                  $ref: '#/components/schemas/repository'
          links:
            repositoryPullRequests:
              $ref: '#/components/links/RepositoryPullRequests'
  /2.0/repositories/{username}/{slug}/pullrequests: 
    get: 
      operationId: getPullRequestsByRepository
      parameters: 
      - name: username
        in: path
        required: true
        schema:
          type: string
      - name: slug
        in: path
        required: true
        schema:
          type: string
      - name: state
        in: query
        schema:
          type: string
          enum: 
            - open
            - merged
            - declined
      responses: 
        '200':
          description: an array of pull request objects
          content:
            application/json: 
              schema: 
                type: array
                items: 
                  $ref: '#/components/schemas/pullrequest'
  /2.0/repositories/{username}/{slug}/pullrequests/{pid}: 
    get: 
      operationId: getPullRequestsById
      parameters: 
      - name: username
        in: path
        required: true
        schema:
          type: string
      - name: slug
        in: path
        required: true
        schema:
          type: string
      - name: pid
        in: path
        required: true
        schema:
          type: string
      responses: 
        '200':
          description: a pull request object
          content:
            application/json: 
              schema: 
                $ref: '#/components/schemas/pullrequest'
          links:
            pullRequestMerge:
              $ref: '#/components/links/PullRequestMerge'
  /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge: 
    post: 
      operationId: mergePullRequest
      parameters: 
      - name: username
        in: path
        required: true
        schema:
          type: string
      - name: slug
        in: path
        required: true
        schema:
          type: string
      - name: pid
        in: path
        required: true
        schema:
          type: string
      responses: 
        '204':
          description: the PR was successfully merged
components:
  links:
    UserRepositories:
      # returns array of '#/components/schemas/repository'
      operationId: getRepositoriesByOwner
      parameters:
        username: $response.body#/username
    UserRepository:
      # returns '#/components/schemas/repository'
      operationId: getRepository
      parameters:
        username: $response.body#/owner/username
        slug: $response.body#/slug
    RepositoryPullRequests:
      # returns '#/components/schemas/pullrequest'
      operationId: getPullRequestsByRepository
      parameters: 
          username: $response.body#/owner/username
          slug: $response.body#/slug
    PullRequestMerge:
      # executes /2.0/repositories/{username}/{slug}/pullrequests/{pid}/merge
      operationId: mergePullRequest
      parameters:
        username: $response.body#/author/username
        slug: $response.body#/repository/slug
        pid: $response.body#/id
  schemas: 
    user: 
      type: object
      properties: 
        username: 
          type: string
        uuid: 
          type: string
    repository: 
      type: object
      properties: 
        slug: 
          type: string
        owner: 
          $ref: '#/components/schemas/user'
    pullrequest: 
      type: object
      properties: 
        id: 
          type: integer
        title: 
          type: string
        repository: 
          $ref: '#/components/schemas/repository'
        author: 
          $ref: '#/components/schemas/user'

Links are defined like this:

components:
  links:
    UserRepositories:
      # returns array of '#/components/schemas/repository'
      operationId: getRepositoriesByOwner
      parameters:
        username: $response.body#/username

And referenced like this:

paths:
     …
      responses: 
        '200':
          description: The User
          content:
            application/json:
              schema: 
                $ref: '#/components/schemas/user'
          links:
            userRepositories:
              $ref: '#/components/links/UserRepositories'

Describe the solution you'd like

Links should provide templates with a means to generate links in responses.

Describe alternatives you've considered

Current workaround is providing link header information manually in the spec document, but this doesn't give sufficient details to generate links via codegen.

Additional context

See link object for full details.

Assignee
Assign to
Time tracking