Re: Documentation for REST APIs

["Elisa R. Sawyer" <elisawyer -at- gmail -dot- com>]

Tom, thanks for this, you filled in some gaps in my knowledge and I really
like your list of caveats in the "slight disillusionment" section. I agree
that while Swagger has a lot of good features, it also presents a few
problems that are difficult to solve.

Just a note, while the Swagger specification describes YAML files, there
are plugins that enable it to accepts other formats. I'm working with a
team that uses YANG files, and while I have not asked, I believe that they
are using the pyang plugin.

I have worked with a team that made use of Openstack's documentation tools.
It is easier to integrate a developer guide with the API reference
documentation generated by their tools. Here's a link:
http://docs.openstack.org/contributor-guide/doc-tools.html

-Elisa

On Tue, Sep 20, 2016 at 1:32 PM, Tom Johnson <tomjohnson1492 -at- gmail -dot- com>
wrote:

> I recently published an article on using Swagger in the ISTC and also made
> it available here: http://idratherbewriting.com/pubapis_swagger_intro/
>
> The article should provide a good grounding about how to use Swagger.
>
> Tom
>
> ---------------------
> blog: idratherbewriting.com
> twitter: tomjohnson
> email: tomjohnson1492 -at- gmail -dot- com
> cell: 408-540-8562
>
> On Tue, Sep 20, 2016 at 3:40 AM, Moshe Kruger <moshe -dot- kruger -at- gmail -dot- com>
> wrote:
>
> > I have had positive experiences with Swagger for documenting REST APIs.
> >
> > A recent project involved several development teams. The leader of one
> took
> > the initiative in this regard and the others followed suite.
> >
> > On Sep 19, 2016 15:41, "Caroline Tabach" <caroline -dot- tabach -at- gmail -dot- com>
> > wrote:
> >
> > > Apologize for some spelling mistakes previously
> > >
> > > > Hi,
> > > > I am preparing documentation for the above.
> > > > From research I can see that there are tools such as Swagger to
> > > > automatically generate.
> > > > 1. Is this how you make the documentation?
> > > > 2. How do you edit the information the developers put in? In the
> > source?
> > > > 3. Do you then export the files or use as is?
> > > >
> > > > Or do you create a regular document with explanations?
> > > >
> > > > Thanks
> > > >
> > > > Caroline
> > > > Caroline -dot- tabach -at- gmail -dot- com
> > > >
> > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > > Visit TechWhirl for the latest on content technology, content strategy
> > and
> > > content development | http://techwhirl.com
> > >
> > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > >
> > > You are currently subscribed to TECHWR-L as moshe -dot- kruger -at- gmail -dot- com -dot- 
> > >
> > > To unsubscribe send a blank email to
> > > techwr-l-leave -at- lists -dot- techwr-l -dot- com
> > >
> > >
> > > Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
> > > http://www.techwhirl.com/email-discussion-groups/ for more resources
> and
> > > info.
> > >
> > > Looking for articles on Technical Communications?  Head over to our
> > online
> > > magazine at http://techwhirl.com
> > >
> > > Looking for the archived Techwr-l email discussions?  Search our public
> > > email archives @ http://techwr-l.com/archives
> > >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > Visit TechWhirl for the latest on content technology, content strategy
> and
> > content development | http://techwhirl.com
> >
> > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >
> > You are currently subscribed to TECHWR-L as tomjohnson1492 -at- gmail -dot- com -dot- 
> >
> > To unsubscribe send a blank email to
> > techwr-l-leave -at- lists -dot- techwr-l -dot- com
> >
> >
> > Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
> > http://www.techwhirl.com/email-discussion-groups/ for more resources and
> > info.
> >
> > Looking for articles on Technical Communications?  Head over to our
> online
> > magazine at http://techwhirl.com
> >
> > Looking for the archived Techwr-l email discussions?  Search our public
> > email archives @ http://techwr-l.com/archives
> >
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as elisawyer -at- gmail -dot- com -dot- 
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications?  Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions?  Search our public
> email archives @ http://techwr-l.com/archives
>



-- 
Elisa Rood Sawyer
~~~~~^~~~~~
Technical and Creative Writer
"Apparently there is nothing that cannot happen today." Mark Twain
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications?  Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions?  Search our public email archives @ http://techwr-l.com/archives