Feat/handle slice aliases

[Sikwan]

Hi guys,

There was a small "regression" (might not have been planned to work before anyway) following commit 2d9c7ef.

What it changed is that now when using aliases for slices, the ref will not be properly filled. Here is a small example, related to the following code:

// Signal
// @openapi:schema
type Signal struct {
    id string `json:"id,omitempty"`
}

// Signals
// @openapi:schema
type Signals []Signal

// AliasesSlice
// @openapi:schema
type AliasesSlice struct {
    Signals signals
}

What it did before:

components:
  schemas:
    AliasesSlice:
      type: object
      properties:
        signals:
          $ref: '#/components/schemas/Signals'
    Signals:
      type: array
      items:
        $ref: '#/components/schemas/Signal'

What it does now:

components:
  schemas:
    AliasesSlice:
      type: object
      properties:
        signals:
          $ref: '#/components/schemas/'
    Signals:
      type: array
      items:
        $ref: '#/components/schemas/Signal'

My changes attempt to fix that, even going a bit further by replacing the alias by the actual struct

What my changes does:

components:
  schemas:
    AliasesSlice:
      type: object
      properties:
        signals:
          type: array
          items:
            $ref: '#/components/schemas/Signal'
    Signals:
      type: array
      items:
        $ref: '#/components/schemas/Foo'

I admit I would go further and remove the Signals schema altogether from the generated documentation but wanted your thoughts on the whole thing before moving further.

@Sadzeih ? @denouche ?

Thanks in advance

[Sadzeih]

Sorry about that! That looks like it's my bad.

[Sikwan]

Don't beat yourself up, we still love you.

[Sadzeih]

Although, I just tried from master, and I don't see the issue you're mentioning.

[Sikwan]

Mind sharing a test? I just redid it and it was the same.

I added this to docparser/user.go:

// TestSadzeih
// @openapi:schema
type TestSadzeih struct {
	Signals Signals
}

I ran a make test (which does not run the tests I just realised ^^), and here was the result:

    TestSadzeih:
      type: object
      properties:
        Signals:
          $ref: '#/components/schemas/'

This was on upstream master.

[Sadzeih]

// @openapi:schema
type TestStruct struct {
	Hello string `json:"hello"`
}

// @openapi:schema
type TestArray []TestStruct

Gives me:

    TestArray:
      type: array
      items:
        $ref: '#/components/schemas/TestStruct'
    TestStruct:
      type: object
      properties:
        hello:
          type: string

[Sadzeih]

// @openapi:schema
type TestStruct struct {
	Hello string `json:"hello"`
}

// @openapi:schema
type TestWrapStruct struct {
	Wrap TestStruct `json:"wrap"`
}

Gives me:

    TestStruct:
      type: object
      properties:
        hello:
          type: string
    TestWrapStruct:
      type: object
      properties:
        wrap:
          $ref: '#/components/schemas/TestStruct'

[Sikwan]

Seems to me your test is not exactly what I am pointing out, you are creating an array of a struct (which works) but not using that new Type as a field in another struct.

[Sadzeih]

Hmm. I got confused by the first example in the description of the PR. I do have the issue when using the slice type in another struct.

[Sikwan]

Because I messed up in it :D Editing that right now.

[Sikwan]

So @Sadzeih, what do you think of the implementation?

[Sadzeih]

So, this implem works, but I actually found where the ACTUAL issue is. This is more of a hack.

It works with struct thanks to this:

openapi-parser/docparser/model.go

Line 571 in 01dbd97

mtd.SetCustomName(entityName)

But this is not done for map or array. Everything should happen in:

openapi-parser/docparser/model.go

Line 520 in 01dbd97

func (spec *openAPI) parseSchemas(f *ast.File) (errors []error) {

[Sikwan]

I'm guessing this would put the name of the alias as $ref which is what it did before the "break" so that's good.

Though I was considering going further and replacing it altogether by the target of the alias.

[Sadzeih]

I think that may require a bit of a rework, if I'm not mistaken. But I wouldn't mind the change, if you're up for it.

[Sadzeih]

What do you think @denouche?

[Sikwan]

@denouche Do you have time to review this one?

[denouche]

Hey, sorry for the delay. I just took the time to read this thread.
If I understand well the debate is what to do between:

• going further and replacing it by the target of the alias
• or just fixing the initial issue
  ?

[Sikwan]

Sorry for the delay as well, don't know how I missed your reply.

I think it could be done iteratively, first avoiding the issue and then going further but I would have to retest with new changes first.

[alexjomin]

Hey Guys, I ran into this same issue and I'm glad to see that PR!

I will check on my side and let you know 🤞

[alexjomin]

Having a nil pointer dereference when generating the doc across my code, investigations in progress.

panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x2 addr=0x40 pc=0x116b5c4]

goroutine 1 [running]:
github.com/alexjomin/openapi-parser/docparser.replaceSchemaNameToCustom(0xc00049d500)
        /Users/alexandrejomin/project/openapi-parser/docparser/model.go:383 +0x144
github.com/alexjomin/openapi-parser/docparser.replaceSchemaNameToCustom(0xc00049c3c0)
        /Users/alexandrejomin/project/openapi-parser/docparser/model.go:369 +0x86
github.com/alexjomin/openapi-parser/docparser.(*openAPI).composeSpecSchemas(0xc000117380)
        /Users/alexandrejomin/project/openapi-parser/docparser/model.go:413 +0x185
github.com/alexjomin/openapi-parser/docparser.(*openAPI).Parse(0xc000117380, {0x2056b9936, 0x100d334}, {0x13f8710, 0x30, 0x30}, {0x1226e64, 0x6}, 0xa8)
        /Users/alexandrejomin/project/openapi-parser/docparser/model.go:295 +0xc9
github.com/alexjomin/openapi-parser/cmd.glob..func2(0x13c5e20, {0x1226891, 0x4, 0x4})
        /Users/alexandrejomin/project/openapi-parser/cmd/root.go:29 +0x13b
github.com/spf13/cobra.(*Command).execute(0x13c5e20, {0xc000126010, 0x4, 0x4})
        /Users/alexandrejomin/go/pkg/mod/github.com/spf13/cobra@v0.0.5/command.go:830 +0x5f8
github.com/spf13/cobra.(*Command).ExecuteC(0x13c5e20)
        /Users/alexandrejomin/go/pkg/mod/github.com/spf13/cobra@v0.0.5/command.go:914 +0x2fc
github.com/spf13/cobra.(*Command).Execute(...)
        /Users/alexandrejomin/go/pkg/mod/github.com/spf13/cobra@v0.0.5/command.go:864
github.com/alexjomin/openapi-parser/cmd.Execute()
        /Users/alexandrejomin/project/openapi-parser/cmd/root.go:41 +0x25
main.main()
        /Users/alexandrejomin/project/openapi-parser/main.go:6 +0x17