09.06.2021, 22:12 | #1 |
Участник
|
waldo: Documenting your Business Central (custom) APIs with OpenAPI / Swagger
Источник: https://dynamicsuser.net/nav/b/waldo...penapi-swagger
============== For reasons that are not too important, I am trying to find a way to “describe my custom APIs”. You know. You’re at a project, you had to implement an integration with a 3rd party application, and you develop some custom APIs for it. When done, you have to communicate this to the 3rd party for them to implement the integration, so you need to pass the documentation, and kind of help through “how to use Business Central APIs”, and a description of the responses, requests and possibilities you have with “typical” Business Central APIs. Disclaimer Now, before I continue, let’s make one thing absolutely clear. I’m by far not an API god, guru, master or whatever you call an expert these days ;-). I’m just an enthusiast, that tries to find his way in the matter .. . The reason for this blogpost is merely because recently I got the question “how do I communicate this API that I just made with the customer that has to use it?“. Let’s see if we can find a decent answer. When you get questions like this, it makes sense to try to find out what they like to get as an answer. What would I expect as a decent, useful description of an API that I’d have to use? OpenAPI / Swagger And we can’t deny that when we need to integrate with something, we LOVE to get some kind of OpenAPI / Swagger description. As such: a document (or set of documents) that defines/describes an API following the OpenAPI Specification. It is basically a JSON or YAML file, that can be represented in some kind of UI to make it very readable, testable, .. . An industry-accepted-standard sort to speak.. There is a lot to say about this, and I don’t want to bore you with the specifics. I’ll simply give you a decent resource for you to read up: OpenAPI Initiative (openapis.org) / OpenAPI Specification (Swagger) . And a screenshot of what it could look like, if you would have some kind of graphical UI that makes this JSON or YAML much more readable: As you can see – a very descriptive page, with a list of API endpoints, a description on how to use them, and even a way to try them out, including details on what the responses and requests would have to be. Even more, this screenshot also shows the abilities: like, I can only read the accounts, but I can read, update and delete trialbalances (if that makes any sense .. ). But .. this does not exist out-of-the-box for Business Central. And this definitely doesn’t exist for custom API’s out-of-the-box, as .. you know, they don’t exist “out-of-the-box” ;-). So .. what CAN we do out-of-the-box? Well, the most basic description we can give to our customer/3rd party is what we call an “edmx” (Entity Data model XML). Which basically is an XML description of your APIs. You can simply get to the edmx by adding “$metadata” to the url. Or even better: “$metadata?$schemaversion=2.0” to also get the enum-descriptions. From the docs: Use OData to Return and Obtain a Service Metadata Document – Business Central Well, I can tell you – that’s not an OpenAPI – and in general, the developers at the customer are going to be a bit disappointed in that kind of documentation. And they are not that wrong. So .. Let’s see if we can convert that edmx in something more useful: an OpenAPI description of our (custom) APIs! I reached out to the twitterz.. and funny enough, it was my own colleague Márton Sági who pointed me in an interesting direction. There is a conversion library in preview https://t.co/p3WYDGEvb4Márton pointed me to this OpenAPI.NET.OData library (and Sergio acknowledged it was a good direction), which, after some investigation, happened to have some kind of converter as well. So .. I tested it out, and it seems something useful comes out of it. Let me briefly explain what I did (after quite some investigation – this really isn’t my cup of tea ).
.\OoasUtil.exe -y -i "C:\Temp\edmx\test.edmx" -o "C:\Temp\edmx\test.yaml"More info on how to use this OoasUtil.exe you can find here: OpenAPI.NET.OData/src/OoasUtil at master · microsoft/OpenAPI.NET.OData. The question is – what do I do with that yaml-file, right? Well, let me get back to where I started: this OpenAPI Specification, is a some kind of default way to describe an API, and the language used is either JSON or YAML. This converter can create both. And this is just the next step to get to that graphical UI that I was talking about. Now comes the easy part .. . You might already have googled “Business Central OpenAPI” .. and it will have you end up on a small page that explains on how to open the standard APIs as a yaml. In fact – there are two pages: there is a page for v1 and there’s a page for v2: – V1: OpenAPI Specification – Business Central | Microsoft Docs – V2: OpenAPI Specification – Business Central | Microsoft Docs The pages are essentially the same, but you’ll see that Microsoft only has prepared this v1 yaml for you (and even that one isn’t downloadable anymore it seems ). The download isn’t available for V2. But guess what – we just created our own yaml! And now you know how to do that for any kind of API as well.. :
You could also use an online service, like SwaggerHub to basically do the same: display the yaml in a UI friendly way, and edit it as well. I tried both – both are very easy to do so. I’m not going to talk about how to do that, as it’s explained good enough on the Docs above. All you need is the yaml, and you’ll be able to use that to visualize it. To make it somewhat easier for you … … I created a small repo. And you can find it here: waldo1001/BusinessCentralOpenAPIToolkit: Business Central OpenAPI Toolkit I tried to explain in the readme on how to use it. What I did is simple. I basically included …
Plans Our plans doesn’t end here though. Just imagine:
Of course, this is for an OnPrem scenario, but kind of the same could be done for BC SaaS. It would just be a matter of deploying the yaml to some kind of SwaggerUI-WebApp (on Azure?). Are there alternatives? As I said – I am by no means any kind of expert in this matter. In the same twitter-conversation, Damien Girard recommends to use “OData Client Library“. I didn’t investigate that yet. Or Stefano mentioned that it’s possible to “embed APIs on Azure API Management” to have Swagger out-of-the-box. I didn’t investigate that either. @Stefano: may be it’s interesting as a blogpost at some point? . Источник: https://dynamicsuser.net/nav/b/waldo...penapi-swagger
__________________
Расскажите о новых и интересных блогах по Microsoft Dynamics, напишите личное сообщение администратору. |
|
|
|