GenieFramework / GenieFramework/SwaggerMarkdown.jl

SwaggerMarkdown.DOCS does not persist package loading if @swagger called inside a package.

Open
#18 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
Julia
Stars
10
Forks
4
PR merge metrics
No merged PRs in 30d

Description

See MWE from this issue: https://github.com/OxygenFramework/Oxygen.jl/issues/280

If I use `@swagger` macro inside my module body, and then load it from the package, DOCS gets empty when I start the server, so if I build docs at this time, I get validation failed error.

`@swagger` expands into a function call in module body, that populates `const DOCS =[]` constant:
```julia
function swagger(doc)
m = @__MODULE__
return esc(quote push!($m.DOCS, $doc) end)
end
```

And if I build docs after package loading, DOCS seems empty in my MWE:
```julia
using Test

# errors:
import Pkg; Pkg.activate(".")
using MyServer
@test !isempty(MyServer.SwaggerMarkdown.DOCS) # test fail
MyServer.main()

# works:
include("../src/MyServer.jl")
using .MyServer
@test !isempty(MyServer.SwaggerMarkdown.DOCS) # test pass
MyServer.main()
```

This results into incorrect `build` handling with empty paths:
```julia
docs_string = join(DOCS)
spec_dict["paths"] = YAML.load(docs_string)
```
end eventually validation fail.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the @swagger macro, the swagger(doc) function, and the SwaggerMarkdown.DOCS initialization described in the issue. Reproduce the package-loading and include-based MWE, then verify that DOCS remains populated after loading the package and that build no longer passes empty paths to validation.

Written by the indexing model from the issue text.

Assessment

Tech stack
julia
Domain
api
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.