Repository navigation
feat: externalValue resolver #1978
Description
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
I have started implementing this and will create a PR for this if it is appreciated in a few days.
Activity
char0n commentedon Mar 15, 2021
@mathis-m,
You're right, it's not being resolved by swagger-js. If you'd like to contribute some sort of resolution for
externalValuethere 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
externalValueifvaluewas defined.2.)
externalValuecan be relative or absolute URLexternalValuecan be either relative or absolute URL. If it's relative it's resolved according to these rules.3.)
externalValueeventual value is not interpreted and is always represented as a stringAfter we resolve
externalValueand 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 underexternalValueURL 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 commentedon Apr 5, 2021
@char0n Would it be ok to remove to resolved externalValue and place the resolved value in the
.valuepath instead.If it should be placed in
.externalValuehow could this be accomplished. Plugin seems to be called whileexternalValuekey 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 commentedon Apr 5, 2021
IMHO most sense is to place the eventual value of
externalValuetovaluefield and rename theexternalValueto$externalValueto mark it as resolved and stop the plugin execution. The benefit of this is that original URI ofexternalValueis still available (if needed via$externalValuefield).mathis-m commentedon Apr 5, 2021
@char0n 2d715a1#diff-4c3af2fb862ab7ff642af33fc7b839f031caf87d40fce8653ddce27261e89ad8R136-R139 like this?
char0n commentedon Apr 5, 2021
@mathis-m yep, seems about right.
mathis-m commentedon Apr 5, 2021
fine then I proceed implementing guards for value and absolutify for the URL.
ambition-consulting commentedon Jul 26, 2021
Any update on this? It would be really great to have this working soon.
mathis-m commentedon Aug 1, 2021
@ambition-consulting I have little time right now, but you are welcome to pick it up
char0n commentedon Sep 10, 2021
Updated point 3.) described in proposed technical design of this implementation: #1978 (comment)