pocinnovation/gingen

A tool to generate an OpenAPI v3 specification from an existing Gin API.

gingen's Issues

[Feature]: OpenAPI skills development

Description

Discover the power of the OpenAPI specification 🔥

Expected behaviour

• Read this introduction to the specification and the getting started
• Play with the online specification editor to learn how the spec works and use Swagger UI also present next to the editor
• Create a server and a client with OpenAPI Generator in the languages you want (try to use different technologies for both 😉) from a specification.

Environment

/

Proposed solution

No response

[Feature]: Setup tests for your comment parser

Description

Make sure your parser works as intended by creating tests 🧪

Expected behaviour

You have to:

• Create sample test files to parse
• Create corresponding sample outputs
• Add test files using those samples
• Setup a CI to run the tests on each commit

You can take a look at previous Go projects made at PoC for this, like DagViz for example 😉

Environment

/

Proposed solution

No response

[Bug]: Functional JSON test is not valid

Description

The JSON used in the functional tests is incomplete 🙁

What happened?

When copy-pasting it in https://editor.swagger.io/ (and converting it to YAML), several errors appear

Expected behaviour

The JSON file should be a valid and complete specification that can be used like any other specification.

Environment

/

Steps to reproduce

You can use the Swagger Editor to make sure your specification is correctly formatted and contains everything 🔥

Relevant log output

No response

Proposed solution

No response

[Feature]: JSON output enhancements

Description

Make sure the JSON output you generate is valid 🔥

Expected behaviour

You have to:

• Refactor the logic to be able to generate a great output matching an OpenAPI specification
• Use https://editor.swagger.io/ to test your output
• Create a sample Go test file with its corresponding JSON output and add it in the CI

Environment

/

Proposed solution

No response

[Feature]: Create a Go comment parser

Description

Parse a Go file to detect the comments that interests you 👀

Expected behaviour

You have to:

• Detect comments written in the particular syntax you defined ⚙️
• Handle begin/start comment to retrieve the code in between
• Keep your program as generic as possible to facilitate further modifications 😄
• Have a look again at previous issues links like go/parser in #6

Environment

/

Proposed solution

No response

[Feature]: Improve the parsing

Description

Improve the parsing performance and generate the right JSON format 🚀

Expected behaviour

You have to:

• Modify the parsing code to uniformize it and parse the Go file only once
• Test your JSON output and think of the format to have a valid OpenAPI specification

Then, you can dig into folder parsing to prepare the next feature ✨

Environment

/

Proposed solution

No response

[Feature]: Setup the base of the project with JSON in Go

Description

Learn how to interact with JSON in Go 🔥

Expected behaviour

Create a simple Go program with those characteristics:

• Take an output filepath as parameter
• Create a JSON file with this path and write sample data inside it
  • Strings
  • Arrays
  • Objects
  • Nested data

Environment

/

Proposed solution

No response

[Feature]: Go skills development

Description

Learn the Go language 🚀

Expected behaviour

Here is what you have to do:

• Follow the entire Go Tour
• Follow this PoC's Go pool day until step 7 included
• Read this article about Go use cases

Environment

/

Proposed solution

No response

[Feature]: Generate a basic OpenAPI specification from parsed comments

Description

Create your first specification from GinGen 🔥

Expected behaviour

Use the comments you parsed using #7 to create a JSON file with basic informations:

• General
  • Title
  • Version
• Endpoints
  • Path
  • Method
  • Summary
  • Response with code and description

⚠️ Use the Swagger Editor to make sure the generated specification is valid

Feel free to go further if you want 🚀

Environment

/

Proposed solution

No response

[Feature]: Create a demonstration worflow

Description

Show a concrete use case of your tool 🚀

Expected behaviour

Here's what you have to do:

• Remove the requestBody for GET
• Add a responseBody to the endpoints where it's missing
• Use a realistic code in the functional tests (like one from the Gin examples)
• Check that the generated specification is valid and use it with OpenAPI Generator to create a server stub in Rust for example

Environment

/

Proposed solution

No response

[Feature]: Gin skills development

Description

Discover the Gin framework 🔥

Expected behaviour

This is what you have to do:

• Follow this PoC's Gin pool day until step 9 included
• Follow this PoC workshop about Gin

Pay attention to the part involving JSON, you'll need it later 😉

• Read this comparison about Go web frameworks

Environment

/

Proposed solution

No response

[Feature]: Brainstorm on the parsing method you'll use

Description

Explore and create the base of the parsing part 🚀

Expected behaviour

• Create a simple program to read a Go file in Go
• Take a look at the go-swagger documentation about spec generation

💡 go-swagger provides a lot of features for OpenAPI specifications v2

• Take a look at go/parser, a package that could be useful 👀

• Create a small presentation / draw some schema about the methods you have considered to parse a Gin API file for OpenAPI spec generation, which one you have chosen and why

Only a single file for now, we'll parse an entire app / folder later

Environment

/

Proposed solution

No response