alexjomin / openapi-parser Goto Github PK
View Code? Open in Web Editor NEWSimple and still naive openapi documentation generator from comments of your Go code.
Simple and still naive openapi documentation generator from comments of your Go code.
// @openapi:schema
type Response struct {
Data external.MoreData `json:"data"`
}
This example will produce:
Response:
type: object
properties:
data:
$ref: '#/components/schemas/external'
instead of
Response:
type: object
properties:
data:
$ref: '#/components/schemas/MoreData'
Fields to support:
We really need to add tests before going further with this project.
Actually I work with a test structure in docparser/datatest
to produce a versioned openapi.yaml. so I can check there is no regression.
Hello,
In the generated file openapi.yaml
the info fields are empty:
info:
version: ""
title: ""
description: ""
The goal of this issue is to find a way to fill these fields.
I have two proposition:
The usage will be like:
// @openapi:info
// version: 1.0.1
// title: Some cool title
// description: Awesome description about what my app do
This block of comment should be present in one file in the sources files. The main.go
seems to be the better place ;)
In this case the parser will use the first @openapi:info
content to fill these data.
The user of the parser needs to have at the root of the project a file named openapi-info.yml
with the content:
info:
version: "1.0.1"
title: "Some cool title"
description: "Awesome description about what my app do"
This file will be used to fill the info fields during the parsing operation.
What do you think about these solutions? Which of them seems more relevant to you?
Or maybe you already think about another way to solve this issue.
In advance thanks
With a type which contains an array of anonymous struct:
type uploadBatchBody struct {
Data []struct {
CreativeID string `json:"creative_id"`
} `json:"data"`
}
We get a segfault:
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x58 pc=0x1185d82]
goroutine 1 [running]:
github.com/alexjomin/openapi-parser/docparser.parseNamedType(0xc00021dc00, 0x12c2800, 0xc000253a10, 0x0, 0x0, 0x0, 0x0)
/Users/user/go/pkg/mod/github.com/alexjomin/[email protected]/docparser/parser.go:106 +0x7e2
github.com/alexjomin/openapi-parser/docparser.(*openAPI).parseStructs(0xc00009f2b0, 0xc00021dc00, 0xc00026a3a0, 0x1b, 0xc00045d820)
/Users/user/go/pkg/mod/github.com/alexjomin/[email protected]/docparser/model.go:403 +0x5b0
github.com/alexjomin/openapi-parser/docparser.(*openAPI).parseSchemas(0xc00009f2b0, 0xc00021dc00)
/Users/user/go/pkg/mod/github.com/alexjomin/[email protected]/docparser/model.go:486 +0x648
github.com/alexjomin/openapi-parser/docparser.(*openAPI).Parse.func1(0xc0002af140, 0x33, 0x12c45c0, 0xc000268340, 0x0, 0x0, 0x18, 0xc000347600)
/Users/user/go/pkg/mod/github.com/alexjomin/[email protected]/docparser/model.go:254 +0xc6
path/filepath.walk(0xc0002af140, 0x33, 0x12c45c0, 0xc000268340, 0xc000347b10, 0x0, 0x0)
/usr/local/Cellar/go/1.14/libexec/src/path/filepath/path.go:360 +0x425
path/filepath.walk(0xc0003f8ba0, 0x1a, 0x12c45c0, 0xc0002fcea0, 0xc000347b10, 0x0, 0x0)
/usr/local/Cellar/go/1.14/libexec/src/path/filepath/path.go:384 +0x2ff
path/filepath.walk(0xc0003f8b40, 0x11, 0x12c45c0, 0xc0002fcdd0, 0xc000347b10, 0x0, 0x0)
/usr/local/Cellar/go/1.14/libexec/src/path/filepath/path.go:384 +0x2ff
path/filepath.walk(0xc00023be80, 0xc, 0x12c45c0, 0xc0002f1e10, 0xc000347b10, 0x0, 0x0)
/usr/local/Cellar/go/1.14/libexec/src/path/filepath/path.go:384 +0x2ff
path/filepath.walk(0xc00023be1a, 0x3, 0x12c45c0, 0xc0002f1ba0, 0xc000347b10, 0x0, 0x0)
/usr/local/Cellar/go/1.14/libexec/src/path/filepath/path.go:384 +0x2ff
path/filepath.walk(0x126b364, 0x1, 0x12c45c0, 0xc00009f380, 0xc000347b10, 0x0, 0x16007d0)
/usr/local/Cellar/go/1.14/libexec/src/path/filepath/path.go:384 +0x2ff
path/filepath.Walk(0x126b364, 0x1, 0xc0000c5b10, 0x1258a20, 0xc0000c5b01)
/usr/local/Cellar/go/1.14/libexec/src/path/filepath/path.go:406 +0xff
github.com/alexjomin/openapi-parser/docparser.(*openAPI).Parse(0xc00009f2b0, 0x126b364, 0x1, 0x1472ad8, 0x0, 0x0, 0x126bcfc, 0x6)
/Users/user/go/pkg/mod/github.com/alexjomin/[email protected]/docparser/model.go:260 +0x93
github.com/alexjomin/openapi-parser/cmd.glob..func2(0x1445c00, 0x1472ad8, 0x0, 0x0)
/Users/user/go/pkg/mod/github.com/alexjomin/[email protected]/cmd/root.go:28 +0x19d
github.com/spf13/cobra.(*Command).execute(0x1445c00, 0xc00009a1c0, 0x0, 0x0, 0x1445c00, 0xc00009a1c0)
/Users/user/go/pkg/mod/github.com/spf13/[email protected]/command.go:830 +0x29d
github.com/spf13/cobra.(*Command).ExecuteC(0x1445c00, 0x1040f4a, 0x142fd40, 0xc000000300)
/Users/user/go/pkg/mod/github.com/spf13/[email protected]/command.go:914 +0x2fb
github.com/spf13/cobra.(*Command).Execute(...)
/Users/user/go/pkg/mod/github.com/spf13/[email protected]/command.go:864
github.com/alexjomin/openapi-parser/cmd.Execute()
/Users/user/go/pkg/mod/github.com/alexjomin/[email protected]/cmd/root.go:40 +0x31
main.main()
/Users/user/go/pkg/mod/github.com/alexjomin/[email protected]/main.go:6 +0x20
And if we just have the anonymous struct:
type uploadBatchBody struct {
Data struct {
CreativeID string `json:"creative_id"`
} `json:"data"`
}
Get get a parsing error, but no crash:
ERRO[0000] Can't parse the type of field in struct error="expr (&{%!s(token.Pos=369) %!s(*ast.FieldList=&{376 [0xc00016adc0] 436}) %!s(bool=false)}) not yet unsupported" field=Data
An anonymous struct could be handled like so:
// @openapi:schema
type SomeStruct struct {
Data struct {
ID string `json:"id"`
} `json:"data"`
}
Outputs:
SomeStruct:
type: object
properties:
data:
type: object
properties:
id:
type: string
Hello,
OpenAPI 3.0 comes with a great feature: links.
https://swagger.io/docs/specification/links/
It could be nice to implement it.
Hello,
the idea behind this enhancement is to see whether the Open Api parser can handle type alias.
For example we can use something like:
// @openapi:schema
type Error = jsonapi.ErrorObject
instead of re-define (duplicate) the struct locally just to add @openapi:schema
This will allow to use external type to describe our API in the swagger file.
Hi,
We are experiencing issue when using the exposed API, with NewOpenAPI().Parse()
.
We are currently calling this statement in a loop (issue will also be raised if call concurrently), and the Parse
behavior relies on a global variable call registeredSchemas
, which is not cleared when NewOpenAPI()
is call.
In our loop case, schemas of the first Parse
are still present in the second Parse
. In a concurrent scenario, schema will be mixed (in a non-deterministic way) and results will also be invalid.
I'll submit a dummy PR in order to encapsulate this type registry inside the openapi
struct in order to make the whole thing thread-safe.
You can easily reproduce the behavior by running this small snippet :
package main
import (
"io/ioutil"
"os"
"github.com/alexjomin/openapi-parser/docparser"
"gopkg.in/yaml.v2"
)
type Repo struct {
Name string
Path string
DocFile string
}
func main() {
repos := []*Repo{
{Name: "repo-a", DocFile: "/tmp/repo-a-doc.yaml", Path: "workspace/repo-a"},
{Name: "repo-b", DocFile: "/tmp/repo-b-doc.yaml", Path: "workspace/repo-b"},
}
for _, repo := range repos {
spec := docparser.NewOpenAPI()
spec.Parse(repo.Path, []string{}, "vendor", false)
specYML, err := yaml.Marshal(&spec)
if err != nil {
panic(err)
}
if err := ioutil.WriteFile(repo.DocFile, specYML, os.ModePerm); err != nil {
panic(err)
}
}
}
Schema from repo-a
will be written in both /tmp/repo-a-doc.yaml
and /tmp/repo-b-doc.yaml
.
Cheers.
// @openapi:schema:CustomName
type RegularType struct {
// properties
}
// openapi:schema
type Response {
Data RegularType `json:"data"`
}
we will get
Response:
type: object
properties:
data:
$ref: '#/components/schemas/RegularType'
CustomName:
type: object
properties:
# properties
Here the ref in Response
should be #/components/schemas/CustomName
Hello,
On empty response body, the content should not be present, as specified in the section Empty Response Body
of https://swagger.io/docs/specification/describing-responses/
For now, the generated schema is:
...
paths:
/foo:
post:
description: foo
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Foo'
description: foo
"204":
content: {}
description: No response body
...
and should be:
...
paths:
/foo:
post:
description: foo
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Foo'
description: foo
"204":
description: No response body
...
Hello,
About this line in the given example:
https://github.com/alexjomin/openapi-parser/blame/master/README.md#L30
Shouldn't it be $ref: '#/components/schemas/Foo'
?
The idea behind this issue is to have some open api tags that we can put on fields on structs to tell to openapi-parser that the field is nullable. The field will be set as nullable only if this tag is present and the field is a pointer to something.
Example:
// Pet struct
// @openapi:schema
type Pet struct {
ID bson.ObjectId
PointerOfString *string `openapi:"nullable"`
PointerOfStruct *Foo
}
In this example, only PointerOfString
field should be nullable
in the generated openapi file.
For example the uint32 type give:
components:
schemas:
Address:
type: object
properties:
exp:
$ref: '#/components/schemas/uint32'
Hello,
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#operationObject
Maybe we could rename the type action struct
for match the name of the model in the specification: Operation
Then these properties are missing:
And the properties Headers
is not in the specification.
It could also be nice if we supports the specification extensions: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#specificationExtensions
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.