go-oas/docs

Automatically generate RESTful API documentation for GO projects - aligned with Open API Specification standard

docs's Issues

[Test] Cover maps with QuickCheck

[RFC] Sane init & Advanced wrappers

Implement 2, or 3 layers of possible initialization?

Based on users choice, or speed of the development:

• Add initializer for "sane defaults"
• Add setters, instead of obviously showcasing nested structs
• Leave possibility for advanced users with maximum flexibility for struct alteration
• Given the last point, implement a MapTransformer interface, in which a user could pass their own map to alter the behavior of the Builder.

[Rel v1.2] CLI

Add CLI support - make it CLI friendly

[Rel v1.5] E2E tests conversion (support)

Add the ability to for Go tests conversion to Cypress/Katalon suites (convert mocked unit tests into e2e tests)

[Rel v1.1] Validation

Add validation to all structures based on OAS3.0.3

Precise description TBD. This will act as a parent task.

[RFC] Packages split & Unexport

1. • Determine what can be an isolated package/module within the project
2. • Unexport everything that shouldn't consider the end-user, and move it to internal
3. • Improve overall readability and ease-of-use to make instantiation of each segment easier - consider func types for chaining sequences?

IDE issue or something missing?

[RFC] Possible milestones?

Few RFCs proposed:

• Postman support (build & push via PM API)
• Go tests conversion to Cypress/Katalon suites (convert mocked unit tests into e2e tests)
• Full on-run support for swagger, no CLI to "generate & serve", just run & enjoy

[RFC] Pre-build dist

Use https://github.com/markbates/pkger

or compile whole /dist into a byte slice...

How to generate example request and response payloads?

Hi,

Is there any example code for how to use go-oas to generate request and response examples for swagger docs?
Do schemas have to be manually specified or is there a way to generate them from golang structs?

Update README & Docs

!Pre-Release action!

The readme should be updated to be concise, for a quick get-go.

Consider publishing GHPages/Docs to accompany it for smaller details that shouldn't be apart of the readme?

[RFC] Migrate from `interface{}` to `RouteFn`

To be more restrictive, migrate from using interface{} for annotator routes to something like RouteFn with int, *OAS as its params?

[RFC] Export swagger examples/models

As support for FE testing & unified FE mocks, support exporting swagger models, to have a single source of truth for those entities on both BE & FE.

Add tests | Coverage checklist

• Add a few example tests

1. Routing 100% + Quick
2. Annotations 91% (and quick tbd)
3. Build
4. Caller 100% + Quick
5. Server
6. Model Transformers
7. Models - New() OAS

Bonus:

• Add benchmarks for possible chokepoints

[RFC] Registration of built handlers

What easier (more transparent way) is there to register documentation handlers for each endpoint?

Also, consider using a service in order to share common endpoint setups?

[BUG] Examples run only from root

When navigating to ./examples and initiating go run *.go it fails at segmentation & nil dereference - because it's expected to be called from the root.

[Rel v1.4] ReDoc

Add ReDoc support as an alternative to SwaggerUI.

It should be feasible with minor adjustments to the current server, but this support will have to wait for more urgent features to be released first.

[CI] Test build failing

Golang Build is failing. Investigate & fix.

[Rel v1.3] Postman

Add postman support via PM API.

Postman support (build & push via PM API).

Further research required to make a sane decision about this feature.

YAML Marshal Ordering

Implement adequate ordering of the map elements, compared to standard OAS 3.0.1.

Current relevant point in the code is build.go:56::transformToMap().

YAML output is valid, but openapi lint is reporting:

Property `<T>` is not expected here

Which happens due to the nature of inbuilt maps.

FYI: Alternative to maps usage was something like this: gist link

But it proved difficult for $ref and deeply nested structs which had to be altered. Should it be revisited?

CI Tasks

• Add Makefile

• Add Linter

• Add Build Pipeline | GH Actions

• Add Tests to the pipeline

• Add release tagging flow

• Add badges for coverals/releases