Expand a spec

[mironovalexey]

Hello. Thank you for the great OAPI processor. Really cool stuff!

Could you please advise me a a most convenient way to json-marshal the expanded spec from Swagger struct. Something like https://goswagger.io/usage/expand.html.

As I see, SwaggerLoader resolves all $ref's (and doing it well). But I don't see an easy way to extract an expanded spec out of struct.

[fenollp]

I believe you can move this

kin-openapi/jsoninfo/marshal_ref.go

Line 13 in 1e76a00

return json.Marshal(otherwise)

5 lines up and that'll do.

[fenollp]

But really this is a pretty weird action to do IMO. What's your use case?

Since there can be $ref cycles (e.g. when describing trees) this action of "expanding the spec" may never complete... To me it sounds more like there is a tooling issue somewhere else.

[mironovalexey]

I believe you can move this

kin-openapi/jsoninfo/marshal_ref.go

Line 13 in 1e76a00

return json.Marshal(otherwise)

5 lines up and that'll do.

Thank you! I'll give it a try.

But really this is a pretty weird action to do IMO. What's your use case?

Pass json to javascript for rendering.

[mironovalexey]

I believe you can move this

kin-openapi/jsoninfo/marshal_ref.go

Line 13 in 1e76a00

return json.Marshal(otherwise)

5 lines up and that'll do.

@fenollp Thank you again! It works, and works fine. But it seems that changing the marshalling behaviour without forking causes a lot of code to be written. I think spec expansion is a pretty useful thing, and since this work is done, it could be switched on by parameter. M.b. something like

type Swagger struct {
    ...
    MarshalExpanded bool,
}

Since there can be $ref cycles (e.g. when describing trees) this action of "expanding the spec" may never complete...

But SwaggerLoader takes care of it.

[fenollp]

What does expanding a spec with a self-referencing schema look like?

[mironovalexey]

I've just tested a huge OAPI reference with such cycling $refs.

...
    "Comment": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "author": {
          "$ref": "#/definitions/ReviewUser"
        },
        "message": {
          "type": "string"
        },
        "comments": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Comment"
          }
        },
        "status": {
          "type": "string",
          "example": "ENABLED",
          "enum": [
            "ENABLED",
            "DISABLED",
            "REMOVED",
            "DRAFT"
          ]
        },
...
}

SwaggerLoader doesn't visit element more then once, and just puts nil to the corresponding Value. So we have null in marshalled JSON which is almost ok.

[fenollp]

Can you explain your use case a bit more? What’s the benefit here?

[mironovalexey]

Documentation.

Imagine a large OAPI spec (several Mb's, a lot of $ref's). It's too much for Swagger UI or ReDoc. In this case we just split the (resolved) spec by operations. One operation - one page. Something like this.

Just as an example:

• https://goswagger.io/usage/expand.html
• https://github.com/swagger-api/swagger-js#swagger-specification-resolver

But kin-openapi supports it rigtht out of the box.

By the way, Swagger UI renders such cycling $ref's as an empty objects (just like kin-openapi does).

[fenollp]

So some HTML-generating tools have issues with larger specs. In this case why not patch these tools directly?
If I understand correctly you want code that just dereferences some $ref.s, just so the spec is a little smaller (which doesn't sound right)?

[mironovalexey]

So some HTML-generating tools have issues with larger specs. In this case why not patch these tools directly?

I'm not talking about HTML generators, but about browser javascript tools like Swagger UI and Redoc. They render spec within the browser. Huge specs simply cannot be processed by the browser in a reasonable time.

If I understand correctly you want code that just dereferences some $ref.s, just so the spec is a little smaller (which doesn't sound right)?

Dereference, then extract slices, corresponding to operations, and pass them to JS renderer. This is a fairly common practice.

Look, this is a typical page, generated from a slice of resolved schema.
But when schema contains oneOf/anyOf, when body/response are very large and deep, such pages are hard to read. In such cases it is quite convenient to use JS renderers.

And kin-openapi can return dereferenced schema, like other tools do, but this option is not just enabled.

[mironovalexey]

I propose to add this feature to kin-openapi. @fenollp, what do you think about that?

[fenollp]

One needs a way to be able to pass context or encoding options when marshalling. If you can find the time to do it and open a PR I'll merge it :)

[bojanz]

I agree that this would be a great feature to have.

Right now running my tests results in an HTTP request to fetch the external schema. And due to #334, I actually get 6 identical HTTP requests and YAML decodes.
So my idea was to use a pre-expanded schema as a workaround, but I'll need another tool to accomplish that.

EDIT: Settled on redocly/openapi-cli, which also supports linting and preview.