OpenAPI / Swagger2 spec generation #30233

mbohlool · 2016-08-08T17:03:36Z

This is alpha version of OpenAPI spec generation. Generated "/swagger.json" file (accessible on api server) is a valid OpenAPI spec with some warnings that will be fixed in next versions of spec generation. Currently it is possible to generate a client using this spec though I did not test the clients.

reference: #13414

Release note:

Alpha support for OpenAPI (aka. Swagger 2.0) specification served on /swagger.json (enabled by default)

This change is

smarterclayton · 2016-08-09T00:20:56Z

pkg/genericapiserver/openapi/exceptions.go

+// fixOperation tries to rename operation IDs to make OpenAPI spec valid. The best solution to repeated
+// ops is to fix it in the source. If that is not possible, the opFix map would let customize the renaming. If the ID
+// is not in the opFix map, the name will be concatenated with a string computed from the path. see inferNamePartFromPath
+// for more information.


How do we fix generation so this is not necessary?

It should be done in api_installer. We should pass unique Operation name for each operation. There were just too many of them. I think it is better to have swagger 2.0 working and mark it as alpha, then fix those.

Pass this function in to the installer as a fixup func so the implementation in this package knows nothing about Kube.

nikhiljindal · 2016-08-11T22:44:00Z

pkg/genericapiserver/openapi/openapi.go

+func (o *openAPI) buildModels() (definitions spec.Definitions, err error) {
+	definitions = spec.Definitions{}
+	for _, decl := range swagger.NewSwaggerBuilder(*o.config.SwaggerConfig).ProduceAllDeclarations() {
+		for _, oldNamedModel := range decl.Models.List {


Why calling it oldNamedModel?

nikhiljindal · 2016-08-11T22:53:19Z

Looks good, mostly naming comments.

Would be good to add unit tests for the new code.
We also have unit tests to test the swagger response from /api at server:

kubernetes/pkg/master/master_test.go

Line 435 in dfcb649

resp, err := http.Get(server.URL + "/apis")

.

We can add a simple test for swagger.json path.

nikhiljindal · 2016-08-17T18:33:45Z

Would be great if we can have unit tests for all methods with non-trivial code.
I will leave it up to you to make a call on which functions in this PR need tests.

mbohlool · 2016-08-18T15:13:42Z

I've added some test that covers most of the code. This is ready for another round of review.

smarterclayton · 2016-08-18T17:19:21Z

cmd/kube-apiserver/app/server.go

@@ -272,6 +272,7 @@ func Run(s *options.APIServer) error {
 	genericConfig.ProxyDialer = proxyDialerFn
 	genericConfig.ProxyTLSClientConfig = proxyTLSClientConfig
 	genericConfig.Serializer = api.Codecs
+	genericConfig.OpenAPIInfo.Title = "Kubernetes"


Do you also have to set version here?

newConfig set both Title and Version to "Generic API Server" and "unversioned". here we just overwrite the title.

smarterclayton · 2016-08-18T17:20:02Z

Has verification failures

nikhiljindal · 2016-08-18T19:54:53Z

Thanks, LGTM.
Feel free to self apply the label when you get all checks to pass.

mbohlool · 2016-08-18T23:50:24Z

@k8s-bot test this issue #30407

mbohlool · 2016-08-19T02:06:09Z

@k8s-bot test this issue #30407

k8s-bot · 2016-08-19T11:21:17Z

GCE e2e build/test passed for commit c5f1d63.

k8s-github-robot · 2016-08-19T11:21:47Z

Automatic merge from submit-queue

piosz · 2016-08-19T13:24:53Z

Godeps/Godeps.json

@@ -1,6 +1,6 @@
 {
 	"ImportPath": "k8s.io/kubernetes",
-	"GoVersion": "go1.6",
+	"GoVersion": "go1.7",


Was this change intentional? If not please revert.

cc @wojtek-t

no it was not. sent the PR to revert it.

nikhiljindal · 2016-08-23T21:26:49Z

Now that we have a separate param, we should mention in the release note that admins can turn off this new endpoint by setting EnableOpenAPISupport = false.

However for admins to be able to turn it off, we will need to expose it as a command line flag in server_run_options and use that to set config.EnableOpenAPISupport.

smarterclayton · 2016-08-23T22:09:52Z

Is there a downside to this endpoint being exposed?

On Tue, Aug 23, 2016 at 5:27 PM, Nikhil Jindal [email protected]
wrote:

Now that we have a separate param, we should mention in the release note
that admins can turn off this new endpoint by setting EnableOpenAPISupport
= false.

However for admins to be able to turn it off, we will need to expose it as
a command line flag in server_run_options and use that to set
config.EnableOpenAPISupport.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#30233 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/ABG_p0A6IpnMGAee9vCam1xj-IO6XUxMks5qi2WngaJpZM4JfQc-
.

mbohlool · 2016-09-12T20:23:52Z

@nikhiljindal, @smarterclayton Sorry I missed these comment. I see swagger is enabled by default and we do not have a server config for it. I don't see any downside having this enabled by default, but I can add server config if you think that is useful.

nikhiljindal · 2016-09-12T23:52:03Z

I am fine with keeping this enabled by default - should probably mention that explicitly in release notes. Right now it says "Alpha support". We use alpha at other places to mean disabled by default.

Re: allowing admins to disable it. Its generally good to allow admins to turn off new features. Not critical.

mbohlool · 2016-09-12T23:57:08Z

Sure, I will send another PR to allow admins to disable it after my improvement #31468 got merged. Do we still have time to change release note of 1.4?

googlebot added the cla: yes label Aug 8, 2016

k8s-github-robot assigned smarterclayton Aug 8, 2016

k8s-github-robot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. release-note-label-needed labels Aug 8, 2016

mbohlool force-pushed the swagger2 branch from 23092ef to 1dd53dd Compare August 8, 2016 17:07

smarterclayton reviewed Aug 9, 2016
View reviewed changes

mbohlool force-pushed the swagger2 branch 2 times, most recently from ded91bb to c661b56 Compare August 9, 2016 02:52

mbohlool assigned nikhiljindal Aug 10, 2016

mbohlool added this to the v1.4 milestone Aug 11, 2016

nikhiljindal reviewed Aug 11, 2016
View reviewed changes

k8s-github-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Aug 12, 2016

mbohlool force-pushed the swagger2 branch 3 times, most recently from 97b3f57 to 61b69af Compare August 18, 2016 15:12

k8s-github-robot added size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Aug 18, 2016

smarterclayton reviewed Aug 18, 2016
View reviewed changes

mbohlool force-pushed the swagger2 branch from 61b69af to fb103cd Compare August 18, 2016 18:43

mbohlool added 2 commits August 18, 2016 13:50

Do not ignore .drone.sec file

ca7180e

Add go-openapi dependencies and update Godeps

0c51663

mbohlool force-pushed the swagger2 branch from fb103cd to e8e81a3 Compare August 18, 2016 21:34

Generates OpenAPI (aka Swagger 2.0) Spec on /swagger.json path

c5f1d63

mbohlool force-pushed the swagger2 branch from e8e81a3 to c5f1d63 Compare August 18, 2016 22:33

mbohlool added lgtm "Looks good to me", indicates that a PR is ready to be merged. priority/backlog Higher priority than priority/awaiting-more-evidence. labels Aug 19, 2016

k8s-github-robot merged commit 5898f87 into kubernetes:master Aug 19, 2016

piosz reviewed Aug 19, 2016
View reviewed changes

nikhiljindal mentioned this pull request Sep 12, 2016

Generate 2.0 swagger spec #13414

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OpenAPI / Swagger2 spec generation #30233

OpenAPI / Swagger2 spec generation #30233

mbohlool commented Aug 8, 2016 •

edited

Loading

smarterclayton Aug 9, 2016

mbohlool Aug 9, 2016

smarterclayton Aug 9, 2016

nikhiljindal Aug 11, 2016

nikhiljindal commented Aug 11, 2016

nikhiljindal commented Aug 17, 2016

mbohlool commented Aug 18, 2016

smarterclayton Aug 18, 2016

mbohlool Aug 18, 2016

smarterclayton commented Aug 18, 2016

nikhiljindal commented Aug 18, 2016

mbohlool commented Aug 18, 2016

mbohlool commented Aug 19, 2016

k8s-bot commented Aug 19, 2016

k8s-github-robot commented Aug 19, 2016

piosz Aug 19, 2016

mbohlool Aug 19, 2016

nikhiljindal commented Aug 23, 2016

smarterclayton commented Aug 23, 2016

mbohlool commented Sep 12, 2016

nikhiljindal commented Sep 12, 2016

mbohlool commented Sep 12, 2016

OpenAPI / Swagger2 spec generation #30233

OpenAPI / Swagger2 spec generation #30233

Conversation

mbohlool commented Aug 8, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nikhiljindal commented Aug 11, 2016

nikhiljindal commented Aug 17, 2016

mbohlool commented Aug 18, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

smarterclayton commented Aug 18, 2016

nikhiljindal commented Aug 18, 2016

mbohlool commented Aug 18, 2016

mbohlool commented Aug 19, 2016

k8s-bot commented Aug 19, 2016

k8s-github-robot commented Aug 19, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nikhiljindal commented Aug 23, 2016

smarterclayton commented Aug 23, 2016

mbohlool commented Sep 12, 2016

nikhiljindal commented Sep 12, 2016

mbohlool commented Sep 12, 2016

mbohlool commented Aug 8, 2016 •

edited

Loading