Documenting your Business Central (custom) APIs with OpenAPI / 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.

Má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 😉).

  1. I cloned the repo and opened the solution in Visual Studio
  2. I built the OoasUtil project
  3. I used the exe to convert the edmx that I saved to a file

This was the command that I used:

.\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.. :

  • Default Microsoft APIs v1
  • Default Microsoft APIs v2
  • Microsoft Automation APIs
  • Runtime APIs
  • Custom APIs

What’s more interesting on these Docs pages, is that it explains on how to display it, and even edit it. Locally, you can use VSCode extensions to edit the API documentation (essentially: the yaml file) and display it with SwaggerUI. There are previewers, there is a way to create your own node app, … .
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 …

  • .. the OoasUtil assembly so you don’t have to clone & compile it anymore from Microsoft’s github. It’s “just there” and the conversion tool is available as an exe.
  • .. scripts to make it somewhat easier to get the edmx from Business Central APIs. We need this in a file, not as a result in some browser. This script (1_.edmx.ps1) will output it to a file.
  • .. the script (2_convertEdmxToYaml.ps1) to convert this edmx to an OpenAPI Specification in yaml
  • .. the javascript to create a SwaggerUI (node app) based on the yaml
  • .. the scripts (3_StartSwagger_.ps1) to run the node app in node.js (you’ll have to install node.js of course).

As an end result, you should have a SwaggerUI-representation with all the goodies you’d expect, all applied to your custom API (like you see in the screenshot above). If you set up the servers in the yaml, you’ll even be able to interactively try the APIs as well (tested and approved 😉).

Plans

Our plans doesn’t end here though. Just imagine:

  • All your customers are on your own docker image
  • Within this docker image, you also provide some WebApp (like this node app) that can display this SwaggerUI
  • When you deploy your app, an up-to-date yaml is begin generated, and your SwaggerUI is being updated with it

This way, you’d kind of like have an up-to-date OpenAPI documentation of all your custom APIs available for your customer at all times. It’s work in progress in our company – and definitely worth the investment in my opinion.. .
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? 😜.

5.00 avg. rating (98% score) - 3 votes

Permanent link to this article: https://www.waldo.be/2021/06/09/documenting-your-business-central-custom-apis-with-openapi-swagger/

9 comments

4 pings

Skip to comment form

  1. Waldo – thank you!

    Getting an error on second script:
    Unhandled Exception: System.IO.FileLoadException: Could not load file or assembly ‘Microsoft.OpenApi.OData.Reader, Version=1.0.8.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35’ or one of its dependencies. Strong name validation failed. (Exception from HRESULT: 0x8013141A) —> System.Security.SecurityException: Strong name validation failed. (Exception from HRESULT: 0x8013141A)

    Any idea why?

    Thanks,
    Silviu

      • waldo on June 25, 2021 at 9:50 am
        Author

      Sorry to hear – I just tested on a fresh PC, and it just works. If you downloaded the zip, it could be that it blocks certain files – make sure you have all files (especially from the “Microsoft.OpenApi.OData” folder).

    1. I had the same issue with the assemblies from the gitgub repo (Strong name validation failed, the downloaded zip was already ‘unblocked’). I downloaded the assemblies via Nuget and replaced the ones in the repo and everything worked.

      • waldo on July 5, 2021 at 9:52 am
        Author

      Thanks for the tip!

      • waldo on July 6, 2021 at 6:16 pm
        Author

      Thanks for this workaround .. it wasn’t a problem when I tested it 🤷🏻‍♂️

    2. Well, it works just fine now. Thanks for your research and the scripts!
      It was very useful.

    • Mikkel Vilhelmsen on July 8, 2021 at 7:45 pm
    • Reply

    Thanks for the article & scripts, we are currently working towards the same thing for our BC APIs, always good to hear what other people and companies are doing.

      • waldo on July 8, 2021 at 8:03 pm
        Author

      Cool! Always nice to see stuff is actually used :-).

    • Domas on September 6, 2023 at 2:31 pm
    • Reply

    Kudos for a such great tool ! Anyone is experiencing issue that edmx properties are missing “Nullable” parameters?
    For example “quantity” has Nullable=”false” and it is correct:

    Meanwhile amountInclVAT does not have Nullable at all which is confusing:

  1. […] Documenting your Business Central (custom) APIs with OpenAPI / Swagger […]

  2. […] My very quick response to Waldo’s message on that thread was “you can embed your custom API on Azure API Management and you have OpenAPI out of the box“, but I’m the first to say that if your goal is ONLY to have OpenAPI definition, maybe using the open source Microsoft’s OpenAPI.NET.OData library is the easy way to go and Waldo has well described the process in this post. […]

  3. […] My very quick response to Waldo’s message on that thread was “you can embed your custom API on Azure API Management and you have OpenAPI out of the box“, but I’m the first to say that if your goal is ONLY to have OpenAPI definition, maybe using the open source Microsoft’s OpenAPI.NET.OData library is the easy way to go and Waldo has well described the process in this post. […]

  4. […] Source : Waldo’s Blog Read more… […]

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.