Are there any plans to implement swagger?

[omani]

Hi all,

first of all thank you for this wonderful piece of software.

I want to ask if there is any plan to implement or provide a swagger overlay.

[rs]

We have JSON Schema implemented already. Ping @smyrman for more info on how it could be used for Swagger.

[omani]

hi @smyrman,

any idea how the json schema could be used for swagger?

[smyrman]

@omani, Swagger 2.0 uses a subset of the JSON Schema Draft4 specification to describe Data Types.

Therefore, the JSON Schema support in rest-layer will eventually make it possible to describe the leagal/expected payload per API endpoint. Please note that the JSON Schema support in rest-layer is still under development, and doesn't yet handle all schema.Validator types nor support custom validators.

[smyrman]

Also please note that no work has started on actually implementing Swagger API documentaiton support (as far as I am aware), which I assume would involve translating a resource.Index into a Swagger 2.0 JSON document

By active use of hardcoding, you might be able to do this in a crude way for your current rest-layer based project, and then call into the JSONSchema API for the payload schema definitions.

Other than that, I assume PRs are welcome:-)

[smyrman]

@omani, Swagger 2.0 uses a subset of the JSON Schema Draft4 specification to describe Data Types.

I was actually mening to refer to definition objects. Sorry about that.

[smyrman]

There is a new version called OpenAPI Specification 3.0.0.

I have been able to generate such a file in part from resource.Index, and validate that it works with the latest Swagger UI. There is however a lot of hard-coding, and there are few things that should probably be changed in the resource package to support it better.

I don't have time to clean it up and contribute it back into a propper PR right now, but I can dump it on a branch in case anyone else want to have a look. I will try to do this in not to long...

[smyrman]

Here is what we have (pretty limited/hard-coded, and influenced by #127 being open):

• https://gist.github.com/smyrman/a0a015f5763f98343d23afcef8b9a0f8

Example usage in an application atm. (where API is a custom struct holding a resource.Index and some other relevant meta information):

// NewDocHandler returns a handler that writes an "openapi.json" file to the
// response, which could be used for documentation UIs.
func (api *API) NewDocHandler() (http.Handler, error) {
	api.ensureIndex()

	doc, err := openapi.RestlayerDoc(openapi.Info{
		Title:       "My Awesome API",
		Description: "Allows access to awesome resources.",
		Version:     "0.0.1",
	}, api.index)
	if err != nil {
		return nil, err
	}

	doc.Servers = []openapi.Server{
		{URL: api.RootURL},
	}

	doc.Components.SecuritySchemes = map[string]json.RawMessage{
		"jwt": openapi.SecuritySchemeJWT,
	}

	doc.Security = []openapi.SecurityRequirement{
		{"jwt": []string{}},
	}

	return openapi.NewHandler(doc)
}

A proper implementation within rest-layer should probably rely more on schema.Schema usage over json.RawMessage and other values for all schema definitions, and encode the schema as part of a MarshallJSON implementation. There is also lots of hard-coded bits (e.g. singular/plural name generation, list of supported content-types) that should get more tight integrations to resources and ResponseSenders etc.

[apuigsech]

@smyrman work looks great as prototype.
Is there any progress regarding this? Should I use @smyrman work as staring point?

[smyrman]

What I have is a bit hard-coded here and there, but we are using it for our own APIs and it works. Make sure all custom FieldValidator implementations implement the jsonschema.Builder interface, or it will error hard.

For any official Swagger support, I think it's pretty far away atm.

[smyrman]

but we are using it for our own APIs and it works

Probably we are not using the exact same version that is in the gist btw... But just scream out (perhaps on slack) if you have any issues using it. Look for #rest-layer on Gopher Slack

[apuigsech]

Based on @smyrman's work I created the rest-layer-openapi with some improvements;

• I am using kin-openapi data model instead of a build in.
• I did some improvements on the OperationIDs, now if it is a sub-resource adds a suffix, for instance; GetPostsOnUser.

There is still some pending work, specially on supporting more Field types and create some documentation and examples, but I think it's quite solid.

An example of usage is;

	// Generate index and bind resources and sub-resources.
	index := resource.NewIndex()
	users := index.Bind("users", user, mem.NewHandler(), resource.Conf{
		AllowedModes: resource.ReadWrite,
	})
	users.Bind("posts", "user", post, mem.NewHandler(), resource.Conf{
		AllowedModes: resource.ReadWrite,
	})

	// Generate openapi3 document.
	doc := openapi.NewOpenapiFromIndex(index, openapi3.Info{
		Title:   " myAPI",
		Version: "1.0",
	})

	// Print openapi3 document in JSON format.
	b, _ := doc.MarshalJSON()
	fmt.Println(string(b))

[smyrman]

Will close this question.

[Dragomir-Ivanov]

@smyrman Shouldn't we mention somewhere in the README that rest-layer-openapi exists?

[smyrman]

Yes, that's probably a good idea. I am not quite confident our generated JSON-schema is a 100% valid with OpenAPI though, so we should be aware of that.

[Dragomir-Ivanov]

Yes, we can decorate the link with EXPERIMENTAL/ALPHA tag.