ZAP API Documentation

[Luigy0x18]

Hello all,

I am starting this thread as part of the ZAP API documentation and to put here all the ideas that we are caming up with, and to manage all the API documentation we need to add or remove from the ZAP.

as more im using the API more used to it im getting but still need some time to get more familiar with it.

So i got the idea of for example gather all the API documentation and add it to a Read th docs as it is a much organized place and maybe rearrange the local ZAP api documentation.

Any ideas or suggestions are welcome.

Regards!

[Luigy0x18]

Well giving my successful post ^_^, i'm replying to myself on the updates that has been made on this topic.

So regarding the OpenAPI statements, https://groups.google.com/forum/#!topic/zaproxy-develop/R4ubDzJC-oI

Any help or person that has been already working on this migration or like me is starting with understanding how OpenAPI works, i would like hear your experiences and how to start with.

For me any hint on this would be useful, i been playing around with the swaggerhub to see how difficult would be to generate this docs. Well it is going to need tome for any of us that would like to see the ZAP Open API up and running in a short time.

So any thought, tips, and help would be welcome and more, if you have already started with this please let me know so we align ourselves on where to go. :) 

Best regards @DocumentationGroup

[Simon Bennetts]

Thanks for starting this thread :)

We are very hopeful that we'll be getting a technical writer to work on the API docs as part of Google Season of Docs (GSoD).

However theres still plenty of work for other people to do!

I'd like the GSoDs writer to concentrate on the higher level - to make it much easier for people to get to grips with the API and to understand how it fits together.

Ricardo (thc202) is working on generating an OpenAPI definition of our current API. This will define the calls but not the responses, which we dont have defined in code.

Areas that I think other people can work on are:

• Improving the existing call descriptions
• Adding parameter descriptions
• Adding response definitions and descriptions

The existing call descriptions can be worked on right now - they are just defined in the relevant properties file, eg:

• https://github.com/zaproxy/zaproxy/blob/develop/zap/src/main/resources/org/zaproxy/zap/resources/Messages.properties#L34-L42
• https://github.com/zaproxy/zap-extensions/blob/master/addOns/alertFilters/src/main/resources/org/zaproxy/zap/extension/alertFilters/resources/Messages.properties#L5-L7

No code changes are required. You just need to find the relevant property file then add or update message properties with the following name conventions:

<component>.api.<type>.<name>

where <type> is one of 'action', 'other' or 'view'

At the moment _some_ of the descriptions give some info about the parameters.

I think that once we have a framework for generating the OpenAPI definitions then we'll want to be able to document the parameters individually.

We'll also want to be able to define what the response structure looks like.

Both of these things will require code changes.

I think that the current mechanism for adding API descriptions works well, so for the parameters how about we adopt the conventions that the keys must be:

<component>.api.<type>.<name>.param.<param_name>

The response definitions will be more complicated, so for those I think we should wait to see how Ricardo gets on.

Cheers,

Simon

[Luis Gil de Bernabé]

Thank you Simon, if any doubts i will get back to this thread.

Thank you!

[Luis Gil de Bernabé]

Hello  all, 

I just created my very first PR: https://github.com/zaproxy/zap-extensions/pull/2167 i will keep on working on this add-ons API descriptions.

BR!