This month, the developer.openstack.org site gets a new look and changes its\u00a0source tooling. Read on for details about how these changes affect your\u00a0project team.<\/p>\n
You might know that the developer.openstack.org site\u00a0documents over 900GET\/PUT\/POST\/DELETE\/PATCH calls for a dozen\u00a0OpenStack services already on the developer.openstack.org site. As a couple of the keynote speakers in Tokyo so elegantly put it, the trustworthiness and\u00a0consistency of the OpenStack APIs influenced their\u00a0decision to run their business workloads in an OpenStack cloud.<\/p>\n
Those interfaces need docs, lots of docs, and not only reference docs. While it takes a huge\u00a0effort to\u00a0maintain accurate\u00a0references<\/a>, we also need to\u00a0document API usage and scenarios.<\/p>\n Now that we’ve written\u00a0both an API Guide<\/a> and a \u201cWriting your first OpenStack application<\/a>\u201d tutorial, we want the site to be\u00a0the go-to location for app devs, product developers, and anyone who needs to unlock the power of their OpenStack infrastructure.<\/p>\n In\u00a0this release, the docs’ platform introduces tooling that lets you\u00a0migrate from WADL to Swagger and integrate RST-sourced documentation with the API reference documentation. The “why” analysis is clear: we must\u00a0community-source this info\u00a0and make it easy to maintain and update so that users can trust it enough to bet their workloads on it.<\/p>\n Later on, this post answers the “how” questions.<\/p>\n Well, we haven’t had to release the API documentation\u00a0like we release services documentation. We have done a lot of maintenance on the site, with bug fixing and so on. But it’s time to take the leap. Last release we made a proof-of-concept. This release we unleash a solution\u00a0that helps us\u00a0make incremental progress toward our goals.<\/p>\n On January 16th, we\u2019ll migrate the Images API WADL and DocBook files to Swagger and RST files. Then we\u2019ll test the build process and the content itself to validate\u00a0the migration.<\/p>\n After testing, we will migrate the files for these services:<\/p>\n Then, the remaining services can migrate their files by using the validated\u00a0tooling.<\/p>\n If you do provide an OpenStack API service, read on.<\/p>\n For the nova project, place your\u00a0how-to and conceptual articles in the api-guide folder in the nova repository. Other projects can mimic\u00a0these patches that created an api-guide<\/a> and build jobs for the Compute api-guide<\/a>. You continue to update\u00a0reference information in the openstack\/api-site repo. However, the source files have changed.<\/p>\n With this release, you can\u00a0embed annotations in your source code if you want to generate the reference information. Here’s an example patch<\/a> from the nova project. Because\u00a0we haven’t had a project do this yet completely, the build jobs still need to be written.<\/p>\n If your project already has WADL files, they\u00a0will be migrated to Swagger files and stored in the api-site repository. The WADL files will be deleted; you can retrieve them\u00a0from Git.<\/p>\n If your project does not have a WADL file, then you write Swagger plus RST to document your API calls, parameters, and reference information. You can generate Swagger from annotations or create Swagger from scratch that you store\u00a0in the api-site repository. You should review, store, and build RST for conceptual or how-to information from within your project team\u2019s repository.<\/p>\n All projects should use this set of API documentation guidelines<\/a> from the OpenStack API working group any time their service has a REST API. This document tells you what and how much to write. If you follow the suggested outline, your API guide will be accurate and complete.<\/p>\n After the source files and build jobs exist, the docs are built to developer.openstack.org.<\/p>\n These\u00a0specifications describe the details:\u00a0Application Developer Guides<\/a>\u00a0and\u00a0Rework API Reference Information<\/a>.<\/p>\n You can ask questions in #openstack-sdks or #openstack-docs on IRC. We await those\u00a0magical API docs fairies who grant wishes, but in the meantime but we can point you in the right direction and give you the tools for your quest.<\/p>\n Contact me, Anne Gentle, by email or IRC and I’ll get back to you as soon as possible.<\/p>\n I’m eager to enable our\u00a0audience with great user-centric docs and hope that you’ll join us as we fulfill the vision.<\/p>\n","protected":false},"excerpt":{"rendered":" Summary This month, the developer.openstack.org site gets a new look and changes its\u00a0source tooling. Read on for details about how these changes affect your\u00a0project team. Why are we changing the developer.openstack.org site? You might know that the developer.openstack.org site\u00a0documents over 900GET\/PUT\/POST\/DELETE\/PATCH calls for a dozen\u00a0OpenStack services already on the developer.openstack.org site. As a couple of… Read more »<\/a><\/p>\n","protected":false},"author":6,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":[],"categories":[21,5,4],"tags":[457,62,511,25,12],"_links":{"self":[{"href":"https:\/\/www.openstack.org\/blog\/wp-json\/wp\/v2\/posts\/7576"}],"collection":[{"href":"https:\/\/www.openstack.org\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.openstack.org\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.openstack.org\/blog\/wp-json\/wp\/v2\/users\/6"}],"replies":[{"embeddable":true,"href":"https:\/\/www.openstack.org\/blog\/wp-json\/wp\/v2\/comments?post=7576"}],"version-history":[{"count":9,"href":"https:\/\/www.openstack.org\/blog\/wp-json\/wp\/v2\/posts\/7576\/revisions"}],"predecessor-version":[{"id":7605,"href":"https:\/\/www.openstack.org\/blog\/wp-json\/wp\/v2\/posts\/7576\/revisions\/7605"}],"wp:attachment":[{"href":"https:\/\/www.openstack.org\/blog\/wp-json\/wp\/v2\/media?parent=7576"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.openstack.org\/blog\/wp-json\/wp\/v2\/categories?post=7576"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.openstack.org\/blog\/wp-json\/wp\/v2\/tags?post=7576"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Why all these changes at this point in the release?<\/h2>\n
How do you keep your API docs updated after January 16th?<\/h2>\n
\n
Where can I get help for my project’s API Guides?<\/h2>\n
What if I still have questions?<\/h2>\n