Add support for $ref in header schemas

[cq-fpietron]

Greetings!

First of all, thanks for all the work on the fastify ecosystem. It's a blast to utilise it in projects.

This PR includes a small adjustment to the way headers are treated in plainJsonObjectToOpenapi3.

The motivation is a scenario from my setup, where I attach some headers validation to most of my routes. They contain either enums or examples that I'd like to be properly passed down to the resulting OpenAPI schema. One of the benefits of this is, in tandem with properly initialising refs, to have its presentation in swagger-ui improved: select fields for enum etc.

I first experimented with injecting example and examples fields directly into the value returned from toOpenapiProp, however I think the approach with $ref is both more elegant and functional.

Please let me know whether: my suggestion is too narrow or not, and is the added test sufficient enough.

I'm also wondering

• if it shouldn't search for $ref within an additional schema property,
• whether the type field next to possible $ref should now be optional or not - best case scenario I'd like to define the $ref only; same goes for description?

PS: isn't the PR template outdated? I see no benchmark script in package.json.

Cheers!

Checklist

• run npm run test and npm run benchmark
• tests and/or benchmarks are included
• documentation is changed or added
• commit message and code follows the Developer's Certification of Origin
  and the Code of conduct

[cq-fpietron]

I'm wondering whether this should be

if (jsonSchemaElement.$ref) {
   result.schema.$ref = jsonSchemaElement.$ref
   delete result.schema.type
   delete result.description
 }

To avoid undefined fields in fastify.swagger()?

[zekth]

As you pass a $ref the property type has no purpose to exist, on the other hand description is still legit to be here. So technically you should only delete result.schema.type

[mcollina]

lgtm

[coveralls]

Pull Request Test Coverage Report for Build 981880591

• 3 of 3 (100.0%) changed or added relevant lines in 1 file are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 100.0%

---

Totals
Change from base Build 981089321:	0.0%
Covered Lines:	537
Relevant Lines:	537

---

💛 - Coveralls

[climba03003]

After checking the generated json, I think this cannot be supported unless we add the support of object property $ref resolution.
The output and the test seems to be fine, but you can see that components.schemas is empty object. swagger-ui will throw error because #/components/headers/someHeader cannot be find.

{
  "openapi": "3.0.3",
  "info": {
    "title": "Test swagger",
    "description": "testing the fastify swagger api",
    "version": "0.1.0"
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "name": "apiKey",
        "in": "header"
      }
    },
    "schemas": {}
  },
  "paths": {
    "/": {
      "get": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "hello"
                ],
                "properties": {
                  "hello": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "in": "header",
            "name": "referencedHeader",
            "required": true,
            "schema": {
              "$ref": "#/components/headers/someHeader"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "http://localhost"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "tag"
    }
  ],
  "externalDocs": {
    "description": "Find more info here",
    "url": "https://swagger.io"
  }
}

[cq-fpietron]

@climba03003 thanks for your checks. I have stumbled into this too. I was able to get it to work in a slightly hacky way, though.

The solution was to use $refs to components/schemas instead of parameters or headers(As per OpenAPI 3.0 components section, components/headers are for response headers, not request headers). I guess it is not as crucial in this case as I have only seen references to components/schemas in fastify-swagger's codebase.

I also had those definitions added to fastify via app.addSchema with $id: '#/components/schemas/someHeader.

It would appear that parsing components/parameters is nearly valid, as I can either get fully valid OA3 schema or one that displays in swagger-ui nicely. I have created a sample repository available here to depict this behaviour: cq-fpietron/fastify-swagger-refs.

Starting up the server you can toggle between registering fastifySwagger with either option.

@climba03003 , do you have any idea how we could estimate work on getting this feature right?

[climba03003]

@climba03003 thanks for your checks. I have stumbled into this too. I was able to get it to work in a slightly hacky way, though.

The solution was to use $refs to components/schemas instead of parameters or headers(As per OpenAPI 3.0 components section, components/headers are for response headers, not request headers). I guess it is not as crucial in this case as I have only seen references to components/schemas in fastify-swagger's codebase.

I also had those definitions added to fastify via app.addSchema with $id: '#/components/schemas/someHeader.

It would appear that parsing components/parameters is nearly valid, as I can either get fully valid OA3 schema or one that displays in swagger-ui nicely. I have created a sample repository available here to depict this behaviour: cq-fpietron/fastify-swagger-refs.

Starting up the server you can toggle between registering fastifySwagger with either option.

@climba03003 , do you have any idea how we could estimate work on getting this feature right?

The fastest way is update the code of resolver in https://github.com/Eomm/json-schema-resolver which fit the needs.
The best way is rewrite a brand new resolver which can solve #337

[davidschmitt]

FYI, I have created a drop-in replacement for json-schema-resolver which solves many of the $ref related issues in external schemas for fastify-swagger.

I've published the code here: https://github.com/davidschmitt/fastify-schema-resolver.git

I haven't published the package on npmjs.com (I've never done that before), but if the fastify-swagger maintainers are interested in switching I can do so.

EDIT: I just realized that while my new resolver fixes fastify-swagger $ref issues for body and response schemas, it does not correct the top level $ref issue for headers, params or querystring schemas. My apologies for posting on this thread

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.