Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: externalValue resolver #1978

Open
mathis-m opened this issue Mar 14, 2021 · 9 comments · May be fixed by #2013
Open

feat: externalValue resolver #1978

mathis-m opened this issue Mar 14, 2021 · 9 comments · May be fixed by #2013
Assignees
@mathis-m
Labels
type: enhancement type: feature version: 3.x

Comments

@mathis-m
Copy link

mathis-m commented Mar 14, 2021 •
edited
Loading

Content & configuration

https://editor.swagger.io/?url=https://gist.githubusercontent.com/mathis-m/262703ffd14ac670366e603d0143943f/raw/4d4d7f3f5a5ba27c9880344976d7297e600588ce/tm8jDkQ5Cq.txt
Swagger/OpenAPI definition:

openapi: 3.0.0
info:
 title: asd
 version: "123"
paths:
 /:
   post:
     parameters:
       - in: header
         name: limit
         schema:
           type: integer
           maximum: 50
         examples:
           max:
             summary: A sample limit value  # Optional description
             externalValue: 'https://gist.githubusercontent.com/mathis-m/ad32902aa510d7e69b4b8d3b02e284a6/raw/613955421088a491231b1c6c7766f0f95a5c5824/vNwATb2zAG.txt'
     requestBody:
       content:
         application/json:
           schema:
             {}
           examples:
             jsonObject:
               summary: A sample object
               externalValue: 'https://gist.githubusercontent.com/mathis-m/e97d480acd5e13455beeba37947d2d8b/raw/9e26dfeeb6e641a33dae4961196235bdb965b21b/z1xx2GHQEY.txt'
         image/png:
           schema:
             type: string
             format: binary
           examples:
             KittenImage:
               externalValue: "https://placekitten.com/200/300"
     responses:
       "200":
         description: OK!
         content:
           application/json:
             schema:
               {}
             examples:
               jsonObject:
                 summary: A sample object
                 externalValue: 'https://gist.githubusercontent.com/mathis-m/e97d480acd5e13455beeba37947d2d8b/raw/9e26dfeeb6e641a33dae4961196235bdb965b21b/z1xx2GHQEY.txt'

Is your feature request related to a problem?

I think #5433 at swagger-ui is only partially a swagger-ui issue!
I have tried to integrate externalValue examples (from params, requestBody, response) into the sample generation process.
I realized that this value is not resolved, I think swagger-js should resolve this just like it resolves refs.
Originally posted by @mathis-m in swagger-api/swagger-ui#5433 (comment)
.

Describe the solution you'd like

I think swagger-js should resolve this just like it resolves refs.

Describe alternatives you've considered

Else ways I will implement some resolver that will fetch the raw value hosted behind the externalValue url within swagger-ui

Additional context

#5433 at swagger-ui

I have started implementing this and will create a PR for this if it is appreciated in a few days.
@mathis-m mathis-m mentioned this issue Mar 14, 2021
Open
@char0n
Copy link
Member

char0n commented Mar 15, 2021 •
edited
Loading

@mathis-m,

You're right, it's not being resolved by swagger-js. If you'd like to contribute some sort of resolution for externalValue there are som rules and complexities involved which I'd like to map in this comment before you commence your work.

1.) The value field and externalValue field are mutually exclusive.

We don't resolve externalValue if value was defined.

2.) externalValue can be relative or absolute URL

externalValue can be either relative or absolute URL. If it's relative it's resolved according to these rules.

3.) externalValue eventual value is not interpreted and is always represented as a string

After we resolve externalValue and fetch it, we don't try to interpret it in any way. By Interpreting I mean trying to parse JSON or YAML strings into JavaScript objects. We always transclude whatever is under externalValue URL as a string. If the file extension is different then .json, '.yamlor.ymlwe shouldbase64 encodethe string before we transclude the resolved value tovalue` field. In future progressive enhancement of this can be implemented processing JSON and YAML into POJO before transclusion.

@mathis-m mathis-m linked a pull request Apr 5, 2021 that will close this issue
Open
10 tasks
@mathis-m
Copy link
Author

mathis-m commented Apr 5, 2021

@char0n Would it be ok to remove to resolved externalValue and place the resolved value in the .value path instead.

If it should be placed in .externalValue how could this be accomplished. Plugin seems to be called while externalValue key exists, so my questions is probably how to mark a fullPath to exernalValue as resolved to not call the plugin with it again and again.

@char0n
Copy link
Member

char0n commented Apr 5, 2021

IMHO most sense is to place the eventual value of externalValue to value field and rename the externalValue to $externalValue to mark it as resolved and stop the plugin execution. The benefit of this is that original URI of externalValue is still available (if needed via $externalValue field).

@mathis-m
Copy link
Author

mathis-m commented Apr 5, 2021 •
edited
Loading

@char0n 2d715a1#diff-4c3af2fb862ab7ff642af33fc7b839f031caf87d40fce8653ddce27261e89ad8R136-R139 like this?

@char0n
Copy link
Member

char0n commented Apr 5, 2021

@mathis-m yep, seems about right.

@mathis-m
Copy link
Author

mathis-m commented Apr 5, 2021

fine then I proceed implementing guards for value and absolutify for the URL.

@ambition-consulting
Copy link

Any update on this? It would be really great to have this working soon.

@mathis-m
Copy link
Author

mathis-m commented Aug 1, 2021

@ambition-consulting I have little time right now, but you are welcome to pick it up

@char0n
Copy link
Member

char0n commented Sep 10, 2021

Updated point 3.) described in proposed technical design of this implementation: #1978 (comment)

@char0n char0n removed their assignment Dec 14, 2021
@mathis-m mathis-m mentioned this issue Mar 18, 2022
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@mathis-m mathis-m

Labels
type: enhancement type: feature version: 3.x
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

feat: resolve external value mathis-m/swagger-js
3 participants
@char0n @ambition-consulting @mathis-m