RestFul API documentation using Swagger

Idea ID 2693975

RestFul API documentation using Swagger

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 https://swagger.io/.

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 : 
https://petstore.swagger.io/

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  

Tags (4)
2 Comments
Micro Focus Frequent Contributor
Micro Focus Frequent Contributor
Status changed to: Waiting for Votes
 
Respected Contributor.. Respected Contributor..
Respected Contributor..

+1 / following

The opinions expressed above are the personal opinions of the authors, not of Micro Focus. By using this site, you accept the Terms of Use and Rules of Participation. Certain versions of content ("Material") accessible here may contain branding from Hewlett-Packard Company (now HP Inc.) and Hewlett Packard Enterprise Company. As of September 1, 2017, the Material is now offered by Micro Focus, a separately owned and operated company. Any reference to the HP and Hewlett Packard Enterprise/HPE marks is historical in nature, and the HP and Hewlett Packard Enterprise/HPE marks are the property of their respective owners.