search

Azure / azure-functions-host

The host/runtime that powers Azure Functions
https://functions.azure.com
MIT License
1.91k stars 435 forks source link

API Definition with Swagger #292

Closed arafato closed 6 years ago

arafato commented 8 years ago

Hello everybody,

how does configuration of API metadata work? I've saved the link to my public Swagger definition in the portal. Is it now automatically providing a swagger-ui web page somewhere? I haven't been able to find it through the standard links such as myazurefunctions.azurewebsites.net/swagger I'm running my functions on the dynamic pricing tier, don't know if that matters. Thanks!

Best regards --Oliver.

mathewc commented 8 years ago

There is no swagger support currently in Azure Functions.

christopheranderson commented 8 years ago

Assigning to Matthew to start investigation.

johnnliu commented 7 years ago

OK. We need this to come back from the backlog.

Flow, Logic Apps, PowerApps, Cognitive Services all work really well with a Swagger definition file. In Satya's Australian developer keynote Swagger is explicitly called out in the developer session right after - as the magic glue that links the different products.

Wishlist:

My ideal scenario is that when you already have a HTTP trigger function, AzureFunction should be able to generate the basic JSON for you.

If you use Request Body with additional JSON input - then the parameter in: type "Body" should be set as well (or at least there should be examples of this).

The JSON file should be hostable from AzureFunction - there are several examples that tells us to spin up a separate API App just to host the JSON file, which I think it's counter to the Severless motto.

If there's integration with swagger.io editor - then the code needs to add swagger.io as allowed in CORS as well. Otherwise, we should be able to run and test the swagger directly in AF.

@Alexkarcher-msft - Hello! IIRC you are the Swagger guy. Pizza helps my memory :-)

In the short term. I think we need some awesome articles from AF on how to build Swagger definition files. It's tricky... Even with a background in WSDL I found YAML hard to digest (as in you need a day to get through).

My current best tip: How to learn Swagger:

  1. http://editor.swagger.io  > Open Example > petstore_full.yaml
  2. File > download JSON
  3. Win

In the next few iterations. Perhaps a single swagger.json file can be exposed under the wwwroot (or per function), and will be served over HTTPS - this allows many web-based Swagger tools to pick up the json easily.

In the long term - dynamic swagger generation :+)

mattchenderson commented 7 years ago

@johnnliu Thanks for the post. We are working on this, but the plan isn't final so it hasn't been assigned a milestone. I'll bump it up to Next so that it doesn't look abandoned. 😃

Would you be able to point to the examples using API Apps to host? That is not a desirable approach, although I suppose it does make for a quick workaround. It is possible to host a Swagger doc from a function app, but it isn't the easiest thing right now.

johnnliu commented 7 years ago

Links I found last week:

https://docs.microsoft.com/en-us/azure/connectors/connectors-native-http-swagger - "blob storage"

https://blogs.msdn.microsoft.com/logicapps/2016/07/31/creating-codeless-swagger-connectors-for-logic-apps/ - use swagger.io and YAML (I'd rather kill myself). Then host in blob again.

https://blogs.msdn.microsoft.com/martinkearn/2015/05/22/get-started-with-azure-logic-apps-and-your-own-api-app-in-5-minutes/ - this is about logic apps and swagger and API APP.

johnnliu commented 7 years ago

This is probably the most active/current article.

https://blogs.msdn.microsoft.com/carlosag/2016/05/09/using-azure-functions-in-powerapps/ - and it doesn't talk about how to host the Swagger json file.

Additionally, I find it lacking parts on how to define the Request.Body (json args) as I think most people will use that over query string.

I also REALLY would like the authentication part to be generated automatically. E.g. if I use AAD auth for my AF, the swagger file should say so, and in Flow it should automatically offer the way to authenticate with AAD account from Flow. - in fact I think this is a critical feature request.

yvele commented 7 years ago

But what about that in Azure Function Portal? How is this helpful? I don't understand this "feature":

image

image

johnnliu commented 7 years ago

Hi @yvele that's what I mean - Functions give a place to put the swagger definition file, but you need to spin up some other web site to host the json file. I think Functions should serve the file too. I can't find good guidance on where to create the file.

xpouyat commented 7 years ago

Some good info here: http://anthonychu.ca/post/restful-apis-swagger-openapi-azure-functions/

johnnliu commented 7 years ago

@xpouyat

I kind of think it's brilliant and sad at the same time that we need to write a second function to return the json file for the first function ;-)

Starting to think it might be cheaper to use Azure Blob Storage and CDN cache link for just one file, depending on how often various services hit the endpoint to grab the json file.

bootsector commented 7 years ago

Sorry to jump in with a question, but why using Functions instead of, for example, Azure API App? I have been working with API Apps for quite some time and it supports everything an Industry Standard PaaS for webservices should support.

From my understanding, Azure Functions is part of WebJobs which is meant for running jobs, giving you an additional option to get a job triggered via a HTTP request and running a "function", in the Cloud.

Is there something I'm missing or should I start migrating all my webservices from Azure API App to Azure Functions (whenever it supports Swagger, at least, of course)?

wobba commented 6 years ago

I wrote a function which dynamically generates a working Swagger def for PowerApps/Flow - http://www.techmikael.com/2017/08/maybe-most-useful-azure-function-ever.html

alexkarcher-msft commented 6 years ago

This has been delivered: https://docs.microsoft.com/en-us/azure/azure-functions/functions-openapi-definition Please create or thumb up more detailed work items, such as full definition generation.

thanks for all the feedback!

wobba commented 6 years ago

@alexkarcher-msft Ok, so we close this one, and create a new issue asking to get a usable swagger definition..no problem :) Then again, I have working code to go from C# to a usable Swagger definition, much like Swashbuckle.

alexkarcher-msft commented 6 years ago

Yep, we already have a work item for a usable/complete definition :) https://github.com/Azure/azure-webjobs-sdk-script/issues/1510

Good work on that blog post as well!

johnnliu commented 6 years ago

both #292 and #1510 looks closed. Still no happy path.

In LogicApps/Flow if we use HTTP Trigger and use "parse JSON" it will generate the OpenAPI schema needed to call that LogicApps trigger. Can we get the same in AzureFunctions?