Add an API spec in Azure Functions
Our starting point today is an Azure Functions App with two functions inside.
This is nice if I want to directly query it, using something like
Invoke-RestMethod. But I wish I could do something more with these functions, like:
- Connect to or from them in Microsoft Flow / Azure Logic Apps
- Import into Azure API Management
- Tie-in 12 other Azure services I don’t know about by the time you read this
- See them in a familiar Swagger HTML interface
- Easily consumable endpoint documentation for users
- Simple “Try it now” buttons in your browser, no code needed
- Consumption by common tools like Postman
With an API specification (spec), your function app has now officially graduated to big kid underwear…and it’s a much easier potty training process than the other one you may be familiar with.
Table of Contents
- Following in footsteps
- Define method verb(s) in functions
- Generate the API definition template
- Modify the API spec
- Take a test drive
- To be continued
Following in footsteps
For the third post in a row, I’m linking the walkthrough on Microsoft’s official docs site. Just saying that feels like a positive change from the past.
In the linked doc, we’re starting at the “Generate the OpenAPI definition” section, and we’ll adapt things to our functions as needed.
Define method verb(s) in functions
The first action described–specifying that our current functions only accept the GET method–now needs to be defined in code, since we enabled GitHub integration in the previous post.
You’ll need to do this for the
function.json file inside both function subfolders:
If you’re doing something different that you don’t know how to define to Azure Functions in code, you can quickly figure out most things:
- Function app settings > change edit mode to “Read/Write” (temporarily)
- Make your change(s)
- Function app overview > Download app content
Generate the API definition template
Summarizing from the walkthrough (click through if you’d like screenshots).
- Function app > Platform features tab > API > API definition
- API definition source = “Function (preview)”
- Generate API definition template
- After 5-10 seconds, a bundle of YAML should appear in the text box
Remember what I just said about “Download app content”? If you do it again now, you’ll see new
swaggerdirectories, with your new
Swagger v2.0 specs can be defined in YAML or JSON; it’s YAML in the portal, but it looks like the Save process converts it to JSON on the back end.
Also of note: “Generate API definition template” immediately populates 6 “Cross-Origin Resource Sharing” (CORS) rules in your functions app. This allows
portal.azure.com, and variations therein to immediately communicate with your function app.
Modify the API spec
Ok, ignore my aside about the code download, get back in the Azure portal! We’ll stay there for consistency’s sake, but granted that you could do these steps in either place.
Two quick asides before we begin:
- This walkthrough uses the Swagger v2.0 spec. I’d love to use the successor, OpenAPI v3.0, but I couldn’t get Azure to accept it as a valid spec. Don’t know if that’s my fault or not, and/or a potential timeline to support it.
- The Swagger v2.0 spec (linked again for extra obnoxious clickability) is useful if you’d like to supplement properties in this section…which I will. New stuff I’ve added either came from Microsoft’s walkthrough or the v2.0 docs.
Review the YAML changes
Instead of a massive screenshot or code block, I’ll link to the GitHub repo highlighting the difference from start (generation) to finished product.
–> Link to full diff <–
Remember, Azure Functions expects a .json definition within a subfolder, so this linked YAML will not change anything. It’s there only to provide a permalink to the YAML evolution, for this blog post’s reference.
Summarize the changes
To give brief context to changes made, and help point out things you can consider when modifying your API spec:
- 3-9: You can add things to the
infoobject, based on the Swagger v2.0 definition
- 18-23: Describe your PowerShellTeamGet function
x-ms-summaryprovide friendly text and help integrate with the Azure platform:
operationIdis a unique identifier
GETonly produces and doesn’t consume. Our example outputs only JSON, but you can support multiple formats, like
- 25-32: Defining parameters
- See the Swagger parameter object docs
- Again, the
x-ms-*attributes are for Azure integrations
- 35-36: Providing friendly text around a successful response (200)
- Here is where you could provide helpful error messages for other error codes (404, etc.) if you’re getting serious
- 39-56: Defining the properties returned in a 200 response
- My objects return Date/Title/Description/Link properties, so I briefly acknowledge each
- Note that
Date’s type is different. Type/Format options are here:
- 68-99: Repeat 16-58 for other functions in your function app
Take a test drive
This step is concisely described in the official doc’s Test the OpenAPI definition section. The brief, no screenshot version:
- Copy your function’s default host key, for authorization
- In the “preview” pane of the API definition screen:
- Security > apikeyQuery
- Change Authentication
- Paste the key in and Authenticate
- Scroll down to one of your GET functions and “Try this operation”
Hopefully you see something like this!
To be continued
That’s it! Your Azure Functions App now has two GET functions, committed via a GitHub repository, defined and documented in a Swagger API spec, and presented to other Azure services.
On the next episode of “Why Did I Agree to This? Someone Please Send Help”, we’ll tie in to Azure API Management, and learn how it complements our serverless API mission.
|Build a Serverless REST API in Azure|
|Part 2: PowerShell in Azure Functions|
|Part 3: GitHub Integration with Azure Functions|
|Part 4: (you are here)|
|Part 5: Azure Functions and Azure API Management|
|Part 6: Serverless API Series Conclusion|