Idea ID: 2693975

RestFul API documentation using Swagger

Status : Waiting for Votes
Waiting for Votes
See status update history
over 1 year ago

Rest API are available on HPAM but there is no associated documentation that describe what is available and how to use it.
there is only a poor pdf that describe the generic concepts. But ,online, nothing describe the model, the attributes, the links, the available values (especially if they are system enumeration)

The only source are text files that can be generated in the designer. Very poor and static for such a solution.

They are a lot a way to expose on web the documentation of model and RESTful api.

The most popular one is a project called swagger

You can consider it as a technical documentation that describe how to use the API.

it is quite the same approach than what HPAM has already done with the self generated WSDL when exposion the documentation for Soap calls.

a sample to illustrate that :

it describe how to deal with the petstore application  : store, pets and users

it describe all the objets, , all the available attributes, which are mandatory, wich are controlled by list,... 

the verbs to manipulate them (get, put post,...)

the response format, the error code lists,...


With such a description standard, everything (or most of it) can be documented and well explained ot the consumer of RestFul API

with the exported yaml file, the consumer can also generate a big part of his code to interact with the API or just import it in tools like PostMan