AWX modernization: Exploring the OpenAPI specification in AWX community documentation

Project Discussions
, , , ,
1

Hi everyone,

I want to follow up on the previous post about the AWX modernization effort with some progress on the developer documentation front.

We’ve just merged pull request (PR) #16221 to render the OpenAPI specification in human readable format as part of the AWX community documentation. This change automatically generates the AWX API reference documentation from the OpenAPI spec and integrates it into the docsite. Our goal is to make it much easier for community developers to explore and use the new AWX API.

Call for feedback

Not only do we want to highlight the new AWX API in the community documentation, we also want to get community input on the implementation. If you have experience with OpenAPI documentation tooling for Sphinx, we’d love to hear your thoughts. Maybe there is a better Sphinx extension we should consider using? Perhaps you might have suggestions to improve the presentation and user experience? We want to get community input and encourage your feedback.

Try it out

To get started with the AWX OpenAPI documentation, perform the following:

  1. Open the AWX community documentation in your browser of choice.

  2. From the navigation pane on the left, select AWX OpenAPI Schema under the Developers category.

  3. On the AWX OpenAPI Schema page, select Explore the AWX OpenAPI Schema. Alternatively, you can download the latest schema file in JSON format.

After the explorer view loads, you can view the API reference documentation. Here is a screenshot of the explorer view:

OpenAPI-Schema-page
OpenAPI-Schema-page1365×819 72.7 KB

Summary

Making AWX API v2 documentation available to the community is part of our broader commitment to providing developer resources. We want to make it easier for community developers to understand AWX internals and contribute effectively. The OpenAPI docs are one piece of that puzzle and there is more to come as we continue improving the developer experience.

13 Likes
2

This is great. I had to butcher the previous API spec as it was exceeding 10MB, and thus wasn’t supported by the API tooling. Thanks for the effort.

With regards to the UI, I don’t have much front-end experience, so I can’t get much more in detail than sharing my view and experience of the webpage.

So, just my 2ct. The simplicity is nice, it’s an easy overview and shows exactly what you’re looking for. It does however also feel like that the webpage is a lot larger than necessary. There’s a lot of blank space between each parameter. I’m also not too sure about the API URL location on the webpage, and it being separate. I feel like the API URL can very well be a part of the main document, as it’s a single entry for most, if not all parameters.

Definitely already an improvement in my eyes, though!

4 Likes
3

Feedback:

  • content is really good
  • layout is way too spaced out. Makes the page feel like an information desert instead of an information resource. Going into dev tools and disabling all the line-height settings I could find and reducing most of the padding by at least half improves things considerably. (I love me some white space, but “modern” web designers go way overboard.)
5 Likes
4

Thanks for the feedback @BoerBart @utoddl

the API spec viewer is based on a project called redoc. The current configuration is pretty out of the box. A cursory search brought me to some info about a pretty extensive theming system. If you or anyone else wants to explore the options, we’d be open to PRs to tweak this usability.

@tvo318 and @oranod’s PR where the spec was added would be a good jumping off point for someone interested in this.

4 Likes
5

Thanks for the info, John!

I might have a go at it, see if I can touch it up here and there.

4 Likes
6

As the Ansible community uses Read The Docs you will get a preview site build as part of your PR, under the CI status click docs/readthedocs.org:awx

image

3 Likes