Open Stack

On 2022-01-18 23:21:21 +0500 (+0500), Mahnoor Asghar wrote:
[...]
> I am an Outreachy intern, working with OpenStack Ironic on improving
> their API reference documentation mechanism.
[...]

Welcome!

> The wider OpenStack community may be facing similar problems
> maintaining their documentation, and it would be helpful to
> understand their perspective and concerns - with respect to using
> such an extension, their expectations from it, collaborating on
> it, and whether they have additional ideas about how we may bring
> API documentation closer to the code.
[...]

Keep in mind that developers of OpenStack's services have
traditionally held the belief that a good public API should be
versioned independently from the software which implements it. One
version of the software may provide multiple API versions, and
there's not necessarily a 1:1 correlation between public REST API
methods and the internal Python API methods which implement them. I
suspect this has driven some of the desire to separate REST API
documentation from the source code itself.

There have been past attempts to implement self-describing APIs,
scraping running services in CI jobs, and so on. I don't recall the
details, but folks who were active in the API SIG likely have a
clearer recollection and can probably relate some of the challenges
encountered with various approaches.
-- 
Jeremy Stanley
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20220118/a526b391/attachment-0001.sig>