Making a Swagger theme that looks like Stripe's API Docs

[Jared Brown]

Has anyone made a Swagger theme that generates docs similar to the layout of Tripit/Stripe's three-column API docs?

https://stripe.com/docs/api

[Max Lincoln]

No... but Slate uses Markdown, and you could easily convert Swagger to Markdown.

I'm not sure if there's currently a template you can use, but it should be fairly easy to create a Strip/Markdown template for any Swagger code generator. There is a swagger-to-markdown project as well, but it hasn't been updated in a few years. The "static api documentation" for swagger-codegen would probably be a good starting template, but might not have been updated to Swagger 2 yet. If you prefer Ruby and are okay w/ hacking on the tool a bit I've got the start of a generator that uses Thor generators, the same framework behind Rails and Padrino generators. It's a small, simple project (the generator is only 81 lines of code) and Thor makes it easy to write generators, but its a young project with zero documentation.

On Tue, Oct 21, 2014 at 8:33 PM, Jared Brown <jared...@gmail.com> wrote:

Has anyone made a Swagger theme that generates docs similar to the layout of Tripit/Stripe's three-column API docs?

https://stripe.com/docs/api

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

[Jared Brown]

Thank you for the great response.

You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/oeMyayrvKRI/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[tony tam]

There is a 2.0 static codegen: 

https://github.com/wordnik/swagger-codegen/tree/develop_2.0/samples/swagger-static-docs 

I'd love to see the templates updated to build stipe-style docs: 

https://github.com/wordnik/swagger-codegen/tree/develop_2.0/src/main/resources/swagger-static 

On Tuesday, October 21, 2014 7:51:36 PM UTC-7, Jared Brown wrote:

Thank you for the great response.

On Tuesday, October 21, 2014 at 10:36 PM, Max Lincoln wrote:

No... but Slate uses Markdown, and you could easily convert Swagger to Markdown.

I'm not sure if there's currently a template you can use, but it should be fairly easy to create a Strip/Markdown template for any Swagger code generator. There is a swagger-to-markdown project as well, but it hasn't been updated in a few years. The "static api documentation" for swagger-codegen would probably be a good starting template, but might not have been updated to Swagger 2 yet. If you prefer Ruby and are okay w/ hacking on the tool a bit I've got the start of a generator that uses Thor generators, the same framework behind Rails and Padrino generators. It's a small, simple project (the generator is only 81 lines of code) and Thor makes it easy to write generators, but its a young project with zero documentation.

On Tue, Oct 21, 2014 at 8:33 PM, Jared Brown <jared...@gmail.com> wrote:

Has anyone made a Swagger theme that generates docs similar to the layout of Tripit/Stripe's three-column API docs?

https://stripe.com/docs/api

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/oeMyayrvKRI/unsubscribe.

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Max Lincoln]

Great!

I wasn't sure if it was migrated because the README says it isn't.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Max Lincoln]

Even better idea - I almost mentioned MiddlemanApp in my first message, but I forgot that Slate itself is based on Middleman. Coincidentally, it looks like Swagger-UI used to be based on Middleman as well.

My generator was really more of a proof of concept that I could parse Swagger documents in Ruby, give them a more navigable API (iterators and random access), and some other syntactic sugar. That way I could use it in Ruby templates. The standalone generator could be interesting, but its more of a proof of concept for how you could use Swagger in existing template or generator frameworks, like Rails, Padrino, and MiddlemanApp.

That brings us back to Stripe. I forgot to mention that Stripe is based on MiddlemanApp. MiddlemanApp happens to also be based on the same technologies I used in my sample generator, but it makes templates so user-friendly you don't even need to know that. You really just need to know about Middleman Templates and TemplateHelpers.

So how would you use Swagger inside Slate? This is probably the easiest method:

1. Start with the sample slate project

2. Rename "source/index.md" to "source/index.md.erb" (you can use other templating langauges like .liquid, but .erb is probably easiest)

3. Modify "source/index.md.erb" by replacing hardcoded Markdown with templates:

      a. If you want to add additional static documentation that's not in the Swagger document (e.g. an Intro paragraph or a links to client API bindings in several languages) then just leave it as Markdown.

      b. If you want to pull in some data from a Swagger document, you can change the Markdown to ERB that uses my Ruby swagger parser to fetch whatever data you need.

      c. If you want, you can also use templates to inject data from other sources, mixing it with the static Markdown and Swagger. A good example might be code samples in Java/Ruby/Python/etc.

So - rather than generating Swagger->Markdown and dropping that into Slate, you can embed Swagger data directly inside your Slate Markdown. You get the choice to use Swagger when you want it, and Markdown or other templates when you don't.

I'll probably throw together a demo Slate/Swagger project sometime in the near future, but not today.

[Jared Brown]

That’s awesome!  Please let me know if you get a chance to throw a demo together.

Jared

[Jan Willies]

Swagger and Slate together sounds really cool, I'd be interested in that as well.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/oeMyayrvKRI/unsubscribe.

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/oeMyayrvKRI/unsubscribe.

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Robert Winkler]

Hi, 

I created a Swagger to Markup (AsciiDoc and Markdown) converter. It takes a swagger.json or swagger.yaml file as input and converts it into an AsciiDoc or Markdown file. The file can be located locally or remotely accessible via HTTP. The Swagger2Markup converter supports the Swagger 1.2 and 2.0 specification.

The primary goal of this project is to simplify the documentation of RESTful APIs. The result is intended to be an easy-to-read, on- and offline user guide, comparable to GitHub’s API documentation. 

https://github.com/RobWin/swagger2markup

I'm also interested to integrate Slate. My next step is to look how I have to create the Markdown files so that Slate can consume them.

Kind Regards,

Roberet Winkler

[Jared Brown]

Sounds great. Let me know once you have Slate integrated.

Thanks

Jared Brown

To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[Max Lincoln]

Out of curiosity, some swagger fields are allowed to contain Markdown. This isn't really an enforced constraint (you can use any text), but projects like swagger-ui and swagger-editor assume it is markdown. If it was asciidoc instead those projects wouldn't render it properly.

Do you covert those fields from markdown to asciidoc when you're converting swagger to asciidoc, or do you assume they are either plaintext or asciidoc already?

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[Robert Winkler]

Hello,

I assumed those fields are plaintext. Thanks for this hint.
Currently I use the converter to reverse engineer an Annotation-based API documentation to a Markup-based documentation like readthedocs.org (mkdocs) or JBake.

To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[Robert Winkler]

Most fields are passend through as-is.
That's why, Swagger to Markdown should not be an issue.
I have to check whether AsciiDoctor supports some Markdown, otherwhise I have to convert them.

To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[Ron Ratovsky]

Technically, all description fields support GFM, hope that helps.

-----------------------------------------

http://swagger.io
https://twitter.com/SwaggerApi
-----------------------------------------

[Sebastian Ortiz Vasquez]

Hi Rob,

The Swagger2Markup is a very nice work.

How can I help you in order to achieve slate like docs from swagger spec?

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsubscri...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/oeMyayrvKRI/unsubscribe.

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsubscri...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsubscri...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/oeMyayrvKRI/unsubscribe.

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsubscri...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

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

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/oeMyayrvKRI/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

[Dale D]

Jens-Ole made an awesome Swagger UI theme that looks very similar to Stripe and AuthO's API docs.

https://github.com/jensoleg/swagger-ui

[Jared Brown]

That theme looks great. It’s off to a good start.

Jared

--

You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/oeMyayrvKRI/unsubscribe.

To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[Jared Brown]

That looks really, really good. Kudos. But I was expecting to see the option to select a programming language like PHP, Java, Ruby, Python and have it show different example code.

I was also surprised that the documentation is not interactive, which seems like a standard of Swagger.

Jared

On Thursday, October 22, 2015 at 7:14 PM, Cory wrote:

The content of the message has not been downloaded yet.

[Larry Kluger]

Readme.io offers swagger docs as a commercial product.

Also, while the 3 column layout looks good at first glance, it does have some ux issues. It assumes a very wide screen since the typical user will also have one or more source files open while consulting the ref docs.

Its whitespace usage within the docs is random, dependent on the sizes of the middle and right content associated with each other. It is better to explicitly plan white space.

Its responsiveness is not so great since it collapses the two right columns into one--but the ui was planned to have the columns side by side.

Instead, I suggest checking out the rest api docs from Google. They've clearly been thinking through the problem.