API Document Management
#
1. Design NotesWhen the front and back end are jointly debugged, it is usually necessary for the back end to give documents to detail the input and output of the interface;
After the backend development is complete, you need to test whether the access gateway is successful.
In order to reduce the sense of fragmentation and improve the user experience of front-end and back-end development, it is necessary to see the API documentation in shenyu-admin and test the API directly.
#
2. How to useThe brief introduce is as follows.
- Back-end development produces API documents in shenyu-admin.
Three methods of
remotely pulling swagger
,manual filling
, andclient registration
are already supported. From the perspective of functional integrity and user experience,remotely pulling swagger
is currently recommended, and the latter two methods will be in Continuous function enhancement in later versions. - The frontend looks at the API documentation in shenyu-admin and starts development.
During joint debugging, developers (including front-end and backend) may use the testing function in shenyu-admin to request APIs directly.
#
3. Set the global environment addressIn actual use, you may have multiple gateway addresses (such as production environment, test environment, or public network environment, intranet environment), you can manage them in Apache ShenYu
Gateway Management System --> BasicConfig --> Dictionary, Set multiple gateway addresses.
DictionaryType: Fill in the value must be
apidocEnv
;DictionaryCode: The identifier of the gateway address has no actual meaning. It is recommended to use
ENV_LABEL_
as a prefix, such asENV_LABEL_OFFLINE
;DictionaryName: Indicates the gateway type, such as filling in
test environment
,production environment
. This value will appear on the API documentation details page;DictionaryValue: Indicates the gateway address, such as http://127.0.0.1:9195. This value will appear on the API documentation details page;
DictionaryDescribe: Give a brief description of what scenario the gateway address is used for. This value will appear on the API documentation details page;
Sort: The numerical value determines the display order of the gateway address;
Status: open or close。
#
4. Support Multiple Ways to Aggregate API Documents#
4.1 Add API Document ManuallyClicking the menu "Document -> API Document" to create api.
#
Create ProjectIf you have not created a project or you want to classify the new API into a new project, you need to create a project.
#
Add API Documentation#
4.2 Remotely pull the swagger registration API Document.Automatically register API documentation by remotely pulling swager documentation. Please refer to Remote pull swagger registration API document
#
4.3 Shenyu Client Annotation Registration API DocumentationAutomatically register API documents through Shenyu client annotations. Please refer to Client Registration API Documentation
This method is recommended if you do not expect to view the full interface documentation details. When you choose this automatic registration method, please turn off the registration method of remote automatic pull swagger, otherwise there will be conflicts.
#
5. Publish APIIf the API has never been published and the user has not used the shenyu-client, shenyu-admin will automatically expose the API described in the API document to the gateway.
After clicking Save, you'll see that the registration data for the API is inserted below the selectors and rules. As shown below:
#
6. Offline API(optional)Special Note: After clicking Offline, the API will still be visible in the API document list, but it will be deleted from the proxy plug-in and metadata management list. Before you republish the API, the gateway will not proxy the API. When you pass through the gateway When requesting this API, an exception will be reported.