Skip to content

docs: section about dropped openapi option #3243

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
georgettica wants to merge 6 commits into from
Closed

docs: section about dropped openapi option #3243

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7e4230a
feat(faq.md): section about dropped openapi option
georgettica Jun 16, 2020
1133126
Update website/content/en/docs/faq.md
georgettica Jun 16, 2020
550de7d
Update website/content/en/docs/faq.md
georgettica Jun 16, 2020
6e8f665
Update website/content/en/docs/faq.md
georgettica Jun 16, 2020
0ac3259
fix(faq): fix boilerplate flag
georgettica Jun 16, 2020
1c194f3
Update website/content/en/docs/faq.md
georgettica Jun 21, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions website/content/en/docs/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,12 @@ $ export GOROOT=$(go env GOROOT)

This will work for the current environment. To persist this fix, add the above line to your environment's config file, ex. `bashrc` file.

## How do I generate OpenAPI Go source files for my APIs?
It is recommended to use [openapi-gen][openapi-gen] for OpenAPI code generation.

Note that in the example on the docs, the flag `-h ./hack/boilerplate.go.txt` is used to allow add the LICENCE comment on the top of the documents and then, it can be removed.
Copy link
Copy Markdown
Member

@joelanford joelanford Jun 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where is the example? I think we should embed that directly in the FAQ.

Note that we're switching to the kubebuilder-based project layout in #3190, so we should make the example work for that project structure (not our existing project structure).

@hasbro17 did you run across an examples in our docs for running openapi-gen that had to change due to the new layout?

Copy link
Copy Markdown
Contributor

@hasbro17 hasbro17 Jun 16, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@joelanford Hmm no. The only place where we mention how to use openapi-gen is in the version upgrade guide right around the time we dropped support for operator-sdk generate openapi.
https://sdk.operatorframework.io/docs/migration/version-upgrade-guide/#v017x

But I guess for the new project layout you'd just need to update the input/output package paths to your API Go types and you can use that:

# Install openapi-gen binary. Although not this way since this pollutes your SDK's go.mod file
$ go get k8s.io/kube-openapi/cmd/openapi-gen

$ tree apis/
apis/
└── cache
    └── v1alpha1
        ├── groupversion_info.go
        ├── memcached_types.go
        └── zz_generated.deepcopy.go

# openapi-gen always needs a go header file so just use an empty one if not needed
$ touch header.txt

$ openapi-gen  --output-base="" --input-dirs=./apis/cache/v1alpha1 --output-package=./apis/cache/v1alpha1 --output-file-base=zz_generated.openapi -h=./header.txt

$ tree apis/
apis/
└── cache
    └── v1alpha1
        ├── groupversion_info.go
        ├── memcached_types.go
        ├── zz_generated.deepcopy.go
        └── zz_generated.openapi.go

Oh also, with Kubebuilder we don't have the // +k8s:openapi-gen=true tags in our <kind>_type.go scaffolds anymore. So you'd probably need to add those to the Go types yourself.

Copy link
Copy Markdown
Contributor

@camilamacedo86 camilamacedo86 Jun 19, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @georgettica could you please check it with the new layout to provide the example? To do that you need use the master branch and run mkdir <projectname>, cd <projectname> and then, operator-sdk init. It will scaffold the project with the new layout.

Copy link
Copy Markdown
Author

@georgettica georgettica Jun 21, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

will it skaffold a current project with the new information? for I got a confusing result.
I ran the command on my current operator and recieved an error but files and folders were created.

When I ran the init command a hack/boilerplate.go.txt was created so if I were using the command in https://sdk.operatorframework.io/docs/migration/version-upgrade-guide/#v017x

and I guess the tags// +k8s:openapi-gen=true were removed for extracting the openapi-gen from the codebase, so a not should refer to that

Copy link
Copy Markdown
Contributor

@camilamacedo86 camilamacedo86 Jul 4, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @georgettica,

SDK is in a process to be integrated with KB which means that its project layouts will be aligned. More info : Integrating Kubebuilder and Operator SDK. If you run operator-sdk init you will scaffold a project with the new layout.

What is missing here is we provide the example and the info let the users know how to do with the Legacy layout and the new one. Is it make sense?



[kube-apiserver_options]: https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/#options
[controller-runtime_faq]: https://github.com/kubernetes-sigs/controller-runtime/blob/master/FAQ.md#q-how-do-i-have-different-logic-in-my-reconciler-for-different-types-of-events-eg-create-update-delete
[finalizer]: /docs/golang/quickstart/#handle-cleanup-on-deletion
Expand All @@ -150,3 +156,4 @@ This will work for the current environment. To persist this fix, add the above l
[client.Reader]:https://godoc.org/sigs.k8s.io/controller-runtime/pkg/client#Reader
[rbac]:https://kubernetes.io/docs/reference/access-authn-authz/rbac/
[goroot-github-issue]:https://github.com/operator-framework/operator-sdk/issues/1854#issuecomment-525132306
[openapi-gen]: https://github.com/kubernetes/kube-openapi/tree/master/cmd/openapi-gen