Self-documenting RESTful API framework

[Jason McVetta]

Recently came across the Swagger specification for describing RESTful APIs.  Looks like a pretty good idea, and includes some cool tools for visualizing an API.  There are REST frameworks for several languages that can document themselves with Swagger output; but not one for Go.  

I'm just starting a project to build a large-ish REST service, and it would be pretty cool/useful if it were self-documenting. Ideally I'd prefer to contribute Swagger support to an existing REST framework rather than roll my own.  Of the several frameworks - gorest, go-rest, go-restful, and goweb - it looks like go-restful might be most suitable.   Seven5 also looks promising, but currently seems broken (tests fail, examples don't work).  

So I am curious if anyone here has experience with go-restful, or has an opinion on which framework would be best suited?  Especially interested in hearing from framework authors.  Is Swagger support something you would like added to your product?

[Cem Ezberci]

go-restful does seem to have swagger support.. see this:

https://github.com/emicklei/go-restful/blob/master/examples/restful-user-service.go

[Jason McVetta]

Awesome - don't know how I overlooked that.  It appears go-restful is the obvious choice for my needs, then.

On Mon, Mar 25, 2013 at 7:06 PM, Cem Ezberci <cem.e...@gmail.com> wrote:

go-restful does seem to have swagger support.. see this:

https://github.com/emicklei/go-restful/blob/master/examples/restful-user-service.go

--
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Ernest Micklei]

As the author of go-restful, I can help you with any problems/suggestions you may find.

^ Ernest

[Jason McVetta]

Hey Ernest,

Awesome product - I'm enjoying it so far.  

One problem I've run into, is that Intellij chokes on the name, either because it contains a dash or because package name differs from import path.  It breaks code completion - see attached screenshot.  Any chance you'd consider renaming the project to just plain "restful"?  The recent trend seems to be removing "go" from Go package names anyways.

Cheers,

Jason

[Ernest Micklei]

Jason,

Renaming the product is fine by me. I was not aware about this trend but I can see how this improves the ease of use.

I will create a new project and keep the old one around so that I do not break anybody else's work.

[Jason McVetta]

Ernest,

Many thanks!   Would it be a good idea to add something like this to the go-restful code to alert users?

func init() {

    log.Println("go-restful has been renamed.  Please update to github.com/emicklei/restful.")

}

Jason

[Jason McVetta]

The trend I've seen is not so much that old libraries are being renamed; but that newer libraries usually aren't named with the "go-" prefix.  

On Tue, Mar 26, 2013 at 6:24 PM, Robby Colvin <geeta...@gmail.com> wrote:

What trend? I haven't seen any trends, nor any push to rename those repositories.

There are plenty of go packages, especially client libraries, that use go-* to name repositories. 

[Rory McGuire]

In your screen shot you didn't type go-restful you only typed restful. so obviously you would get no completion.

[Dan Kortschak]

go-restful is not the package identifier, restful is. If IntelliJ is not
completing this then that is a problem with that IDE (gocode completes
the suffix of a hyphenated package perfectly well).

Package maintainers should not be changing their package names because
an IDE cannot correctly handle Go package identifiers, that broken tool
should be fixed.

[Jan Mercl]

On Wed, Mar 27, 2013 at 9:08 AM, Dan Kortschak
<dan.ko...@adelaide.edu.au> wrote:
> go-restful is not the package identifier, restful is. If IntelliJ is not
> completing this then that is a problem with that IDE (gocode completes
> the suffix of a hyphenated package perfectly well).
>
> Package maintainers should not be changing their package names because
> an IDE cannot correctly handle Go package identifiers, that broken tool
> should be fixed.

It's a capital sin to publish a package 'foo' with import path
"service.bar/baz/qux" (usually unnecessary inclusion of 'go' aside). I
don't know if it's the case of this package, but I'm sure I saw such
thing on Github. The idea behind it misses me completely.

packageName == importPathBasename, no other sane option exist. This
also automatically rules out any punctuation, which is yet another
craziness.

-j

PS: Insert IMHO where appropriate.

[Dan Kortschak]

I agree. I'm torn. I don't particularly like the idea of the go[.-]
prefix, but I dislike more the idea that an IDE's fault will result in
changes to behaviour that is otherwise legal.

I remember 15-20 years ago when the same prefix argument was being had
over species prefix for gene names. The wrong side won that argument.

[Rory McGuire]

ah, I see what you mean about the folder not matching the package declaration.

--
You received this message because you are subscribed to a topic in the Google Groups "golang-nuts" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/golang-nuts/zhNhLPmVXkg/unsubscribe?hl=en-US.
To unsubscribe from this group and all its topics, send an email to golang-nuts...@googlegroups.com.

[J...@xuu.cc]

Why not use the import as syntax?

Import restful "github.com/emicklei/go-restful"

[dwe...@rmn.com]

@Ernest

It appears swagger-doc has a stub wiki page for Golang. https://github.com/wordnik/swagger-core/wiki/Go-Integrations

go-restful would fit really nicely on that page

On Saturday, October 12, 2013 5:07:56 PM UTC-5, J...@xuu.cc wrote:

Why not use the import as syntax?

Import restful "github.com/emicklei/go-restful"

This e-mail, including attachments, contains confidential and/or proprietary information, and may be used only by the person or entity to which it is addressed. The reader is hereby notified that any dissemination, distribution or copying of this e-mail is prohibited. If you have received this e-mail in error, please notify the sender by replying to this message and delete this e-mail immediately.

[Frank Schröder]

Hi Ernest,

when you rename the github repo github maintains a forward from the old to the new name. So they'll find it and the compiler will tell them that the pkg name has changed.

Done this for goproperties -> properties

Frank