Change Details

The AQS 2.0 project is currently evaluating an OpenAPI-based toolset to create API docs: * **[Swag](https://github.com/swaggo/swag)** generates an OpenAPI specification based on a mix of code annotations and the code itself. * **[RapiDoc](https://github.com/rapi-doc/RapiDoc)** converts the specification into HTML. Our goal is to create API docs that are reliable and easy to update by maintaining docs as close as possible to the code. Add your feedback about these tools to the [[#Evaluation|evaluation notes on wiki]]. --- ### To do [] Add general API information: This needs to be done before documenting individual endpoints. See the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Adding_swag_docs_to_an_API) for instructions. [] Document /:project/:access-site/:granularity/:start/:end ### How to document an endpoint 1. Add code annotations to document the endpoint. See the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Documenting_an_endpoint). 2. Annotate the response format by adding an example and a description to each attribute. See the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Annotating_the_response_format). 3. Generate the spec using swag. See the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Generating_the_API_specification). 4. Preview the spec by loading the docs/swagger.json file into the [RapiDoc demo](https://rapidocweb.com/examples/example1.html). For more options, see the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Viewing_the_API_specification).

The AQS 2.0 project is currently evaluating an OpenAPI-based toolset to create API docs: * **[Swag](https://github.com/swaggo/swag)** generates an OpenAPI specification based on a mix of code annotations and the code itself. * **[RapiDoc](https://github.com/rapi-doc/RapiDoc)** converts the specification into HTML. Our goal is to create API docs that are reliable and easy to update by maintaining docs as close as possible to the code. Add your feedback about these tools to the [[#Evaluation|evaluation notes on wiki]]. --- ### To do [x] Add general API information: This needs to be done before documenting individual endpoints. See the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Adding_swag_docs_to_an_API) for instructions. [x] Document /:project/:access-site/:granularity/:start/:end [] Review ### How to document an endpoint 1. Add code annotations to document the endpoint. See the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Documenting_an_endpoint). 2. Annotate the response format by adding an example and a description to each attribute. See the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Annotating_the_response_format). 3. Generate the spec using swag. See the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Generating_the_API_specification). 4. Preview the spec by loading the docs/swagger.json file into the [RapiDoc demo](https://rapidocweb.com/examples/example1.html). For more options, see the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Viewing_the_API_specification).

The AQS 2.0 project is currently evaluating an OpenAPI-based toolset to create API docs: * **[Swag](https://github.com/swaggo/swag)** generates an OpenAPI specification based on a mix of code annotations and the code itself. * **[RapiDoc](https://github.com/rapi-doc/RapiDoc)** converts the specification into HTML. Our goal is to create API docs that are reliable and easy to update by maintaining docs as close as possible to the code. Add your feedback about these tools to the [[#Evaluation|evaluation notes on wiki]]. --- ### To do [x] Add general API information: This needs to be done before documenting individual endpoints. See the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Adding_swag_docs_to_an_API) for instructions. [x] Document /:project/:access-site/:granularity/:start/:end [] Review [] Document /:project/:access-site/:granularity/:start/:end ### How to document an endpoint 1. Add code annotations to document the endpoint. See the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Documenting_an_endpoint). 2. Annotate the response format by adding an example and a description to each attribute. See the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Annotating_the_response_format). 3. Generate the spec using swag. See the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Generating_the_API_specification). 4. Preview the spec by loading the docs/swagger.json file into the [RapiDoc demo](https://rapidocweb.com/examples/example1.html). For more options, see the [docs on wiki](https://wikitech.wikimedia.org/wiki/AQS_2.0#Viewing_the_API_specification).