Automatic document generation of API--based on CDIF basic capabilities of SOA

Currently, as a standard connection between most mobile apps and the cloud service backend, theREST API has been recognized and widely used by most developers. In recent years, in the emerging API economic model has emerged, many vendors have their back-office capabilities as a REST API open to the wider use of third-party developers.

However, managing the REST API is not an easy task. Due to the lack of an effective schema constraint on the interface data, coupled with the arrangement of resource endpoint when designing the rest API, and the way in which HTTP requests are sent,after the rest API development is complete, In most cases , API developers still need to manually write API documentation, allowing users to follow the documentation instructions. and rewriting the document when the API changes, the process is laborious and error-prone. For example, a REST API document must specify the following basic information at a minimum:

* Name of the API

* URL resource path where API is located

* HTTP request method (GET, POST, put, etc.)

* How the API submits data (query parameters, form submissions,JSON submissions, etc.)

* Call API to return data format

In the REST API information provided above, the JSON data returned from the API can be used in most cases to illustrate the structure of the data in the form of "example ", rather than accurately expressing this The exact meaning and type definition of each field in the JSON data. This is because the REST API lacks a schema definition for JSON data , and this "example " is undoubtedly a very helpless and silly approach. When we are in the development of the interface with other vendors, often the other side of the document is not clear, the need to manually confirm the communication, even if we have the correct understanding of a data parameter or return results, this is a very time-consuming work.

When the business changes, any of the above information about the REST API changes, such as adding a new field to the return result, the developer has to re-write the document again and then resend the document to the API user changes, which can be painful if repeated iterations occur. While there are some API design and documentation tools, such as the Swagger UI, which help developers to write documents more easily, they do not eliminate the complexity inherent in the REST API.

This API management solution is a perfect solution to the REST API documentation issues described above. Cdif is the world's first JSON-based SOA solution. The REST API managed by Cdif can automatically generate their API documentation, saving developers time and effort in managing API documentation. the frame design of the cdif can be represented by:

650) this.width=650; "title=" cdif frame chart. png "src=" https://s5.51cto.com/wyfs02/M00/8F/7B/ Wkiol1jgpzkjzx0kaaavplc-rh8602.png "alt=" Wkiol1jgpzkjzx0kaaavplc-rh8602.png "/>

In Cdif, the rest API is packaged uniformly into a variety of driver packages, each of which is a standard node. js NPM package. Each driver package can contain access code for any number of rest APIs. In the implementation of the driver package, each REST API must provide a unified, common API model for the client, according to the specifications provided by CDIF. This API model is a JSON document that contains all the information about how to access the API. Compared to the rest API documentation above, this API model contains only the following information:

* Name of the API

* JSON schema definition for API input parameters and return results

Other information about the rest API is considered an internal implementation of the API driver package and does not need to be exposed to external API users.

API models based on the CDIF definition specification have API descriptions that are equivalent to XML-based WSDL. Based on this, the API management tools associated with CDIF can automatically parse this JSON document and automatically generate documents from its managed Rest API. is a clear and easy-to-read SMS API document that is automatically generated on the API market made using CDIF:

650) this.width=650; "title=" automated document generation article picture. png "src=" https://s5.51cto.com/wyfs02/M01/8F/7D/ Wkiom1jgp56jdub5aasdiukjg-e869.png "alt=" Wkiom1jgp56jdub5aasdiukjg-e869.png "/>

in the above api document, the type, description, constraints, API error messages and so on, all from the user in api package json schema file is automatically generated, and really do api and data 100% accurate description. Developers only need to follow CDIF provides a specification definition written api model, upload a only dozens of lines Span lang= "en-us" xml:lang= "en-US" >API access code npm package to Cdif-based api management platform, you can have this ability. When api parameters or return results need to be updated, users only need to update NPM package json schema file content, re-upload will automatically obtain a new api documents.

and access to this isCDIF Management ofREST API, the user only needs to accessCdif to be managed by theThe REST API provides a fixedURL address is available, and only client support is requiredhttp post method to submit api request data. All submitted data, according to json schema constraints, all placed in The HTTP request and the returned json body. This design is the classic wsdl + SOAP implementation, very simple to use and good compatibility. At the same time, thanks to json schema of the strong performance capabilities, cdif can support any complexity of API interface data. At present, most popular development languages support the use of post json data to submit api request, So cdif provides api access to the most extensive client development environment support. In the future, we will add clients of various languages API access code auto-generation capability, API users simply copy and paste code to access, further simplifying the api development and use of the process.

In addition, when the internal implementation of the API package needs to change, the user only needs to modify the API package code, re-upload and can deploy a new version with a single click. CDIF supports hot swapping of API package code, and does not even affect the process of invoking an older version of the API that is occurring on the line . This greatly facilitates and simplifies the developer's API development experience.

Furthermore, developers can automatically have API test pages for API developers and API users to easily debug API usability after uploading the API package. This feature, please refer to the next article: API test Automation-based on CDIF's basic SOA functions.

This article from "Apemesh" blog, reproduced please contact the author!

Automatic document generation of API--based on CDIF basic capabilities of SOA