Support Swagger for ArcGIS Server REST endpoints

[DaveTimmins]

The current REST API endpoints for the ArcGIS server services directory and administration allow you to get some useful information and test operations but the documentation is very basic and when complex inputs are required there is no help at all really. By adding Swagger support you could provide the user with a much richer experience and make the API more self documenting.

[JenniferLang]

It seems like many other APIs have a swagger page. Why hasn't ESRI followed industry best practice. I'd love to learn how it use it better and I find I learn better if I'm doing rather than reading pages and pages of documentation.

[RPW]

We also require Swagger / Open API support for our ArcGIS Server REST endpoints to register our web services with Azure API Management and data catalogues. Currently, we need to create Swagger files manually, and are considering developing a tool that could automate this process. However, it would be much easier if ArcGIS Server supported the Open API standard by default. I understand that GeoEvent Server supports Swagger, so there seems to be partial Esri support for it.

If anyone has tips or more information, it would be highly appreciated.

[LaurensKusse_hhdelfland]

I thought Esri finally solved this issue by implementing OGC feature service. 

I tested this service-type (with ArcGIS Enterprise 11.3) and it does provide a json that says "openapi": "3.0.3" and a html that says: 

The API document provides a machine processable description of this service API conformant to api 3.

Unfortunately it still is not OpenAPI compliant. So you can't import it into Swagger or Azure APIM. 

Support told me this request is accepted for one of the coming releases: ENH-000122818: Request to support an OpenAPI specification with the ArcGIS REST API  (I can't find this enhancement myself. Maybe I don't have access)

If anyone has tips or tricks how to create a correct json, from the OGC Feature-service-json, that would be appreciated. 

I tried comparing with OGC feature services with a correct OpenAPI specification, that I found over here: https://api.hamburg.de/datasets/v1

But I'm not yet successful.