search

alphagov / tech-docs-gem

Gem to distribute the tech docs project
https://tdt-documentation.london.cloudapps.digital/
MIT License
15 stars 38 forks source link

Improving the OpenAPI reference docs - any other users? #172

Closed tijmenb closed 3 years ago

tijmenb commented 4 years ago

Hi all,

At DfE we've briefly used the API reference feature in the tech docs template, but found it was too buggy and incomplete to use. We then forked it, but eventually decided to merge our documentation site into our main application. We've since done a significant rewrite of the code.

The result is here: https://www.apply-for-teacher-training.education.gov.uk/api-docs/reference

My preference would be to create an OpenAPI spec renderer that can be used by other GOV.UK services as well. Before we try to extract it from the app I'd like to check if there's interest, and find out if anybody is using the current OpenAPI spec.

If you are using the API spec, or are otherwise interested, leave a comment!

richardTowers commented 4 years ago

I know at least alphagov/verify-service-provider has swagger / OpenAPI documentation, but they ended up doing their own thing with ReDoc by the looks of it. That probably indicates there's a need for better OpenAPI support.

heathd commented 4 years ago

We ended up building something with slate/widdershins for GOV.UK Pay because the implementation in tech docs was incomplete. My worry about building something bespoke is that the OpenAPI spec is quite complex and so full support for every aspect of it is challenging.

There's a lot going on in the API space, and both free/open source and commercial tools are evolving fast. For example I think that eg. Companies house use dapperdox to document their api. This has a different model of a golang server that serves the documentation so it has dynamic features including an api explorer that lets you try out the api. I think HMRC also have a bespoke API documentation frontend.

On the other hand, if you've made improvements that get API docs feature in the tech docs format to a point that it's functional then it might be enough for some folks to start using it and contributing back. We might use it eventually on Pay but on the other hand most developers on our team are not rubyists so it wouldn't be so likely to get significant contributions from us even if we did use it.

There's an API channel in x-gov slack would be worth mentioning there. There's also a x-gov API community (run by Rosalie) I'll mention this to her.

mikebell commented 4 years ago

Hey folks. I'm the author or the original code (sorry about that).

To give some background on the current implementation it's basic to say the least, given timescales and OpenAPI complexity is was impossible to get 100% coverage of the spec. However it works for the use case that we were given.

In hindsight I'd have preferred to completely abstract away the parsing of the spec into another tool that does a better job and then import the outputted html/md into tech-docs, but we had limitations on how we could implement it (ruby only).

I'm currently using tech-docs to build the documentation for my current project and there may be some crossover of functionality in terms of referencing external html/md and bringing it in on build (readme.md files in other repos that need to be aggregated for simplicity).