This is a transcript from Vincenzo Chianese’s lightning demo at
The Austin Homegrown API Meetup in August 2019.
What I have here is nothing more than a basic OpenAPI specification. You can download this from the offshore repository, just to give you the baseline.
And so, Spectral, again, you give it this file. It’s going to analyze the file, and it’s going to show you what it thinks is not okay. We do in OpenAPI specification. It’s telling me the operation should have in our empty tag array on line 18. And so, I can just go here and fix this by doing “tags” and “test” too. And if I save the file and I run it again, the line 19 is not there anymore.
But given it’s customizable, I can also do:
skip-rule-operation-tags
And this time it’s going to skip the whole thing. And I can do the same with multiple rules. So again:
skip-rule-operation-model-description.
If I type it correctly, now you just see the warnings that you want to see.
Spectral also supports configuration file. So what I can do, is create this special file in saying: the rule set that I want to apply to my whole company, it’s a file. You can put in your GitHub repository and share it everywhere in the company. You can create the way you do you APIs.
If you don’t define a tag in this particular example, it’s an error. And so you’ll see ICD should fail. So what I can do, I can try to link this file again. I’m going to just remove this. And do:
ruleset= /.spectral.notags.yml
And so you can see that the error that is put away from the tool has been changing.
This is the set of the rules that we think are okay for OpenAPI, but of course you have your own one in your company. And so what you can also do, you can define your own rule set. I’m not going to go into the DSL because you have the documentation, you can check it out. But the idea is, you can say: if the info object and in particular the tether of field is not equal to Stoplight, I want to say this is a style error. And so if I run this thing again using these other configuration file, “.stoplight.yml,” it’s going to output my custom error. The info should contain Stoplight.
And so you can also programmatically change it, defining your own style guide. And so that when everybody comes in your company, you have a new developer is starting to do an API, is going to be guided through the right way. Because the linter is going to yell at him continuously.
“And this tool is also offering a JavaScript API, and so you can easily integrate it into your CICD.”
One of the things that I did using Spectral. I’m not sure if you noticed it, but the GitHub has been releasing the actions, which is a way to hook up into your repository whenever you’re pushing. And so what I did is whenever I push something into my repository, I want Spectral to check out what my API looks like. And so the result is something like this:
You can easily see directly from GitHub what is wrong with your API, if that’s okay. And if you click on the link, you’re going to go directly to the line and you can comment on it and iterate it, just because we have a JavaScript API and you can use it.
So again, Spectral, this is the OpenAPI 2 entry linter, which is extensible and so on and so forth. Feel free to check it out. This is the first thing that I wanted to show you. The second thing which can help you in case you’re doing a lot of APIs, it’s a rapid iteration. So you have an OpenAPI specification and you want to get a sense, how is it to work with such API? Because, if you follow the waterfall model, you do the API, you give it to your developers and they’re like, “Eh, what did you do? I don’t want this.” So it is important to involve the people in the feedback and move it from the very end to the very beginning of the process.
“It is important to involve the people in the feedback and move it from the very end to the very beginning of the process.”
The tool I’ve been working on for, I think probably the last five months, has been Prism, which is an open source mock server for OpenAPI 2 and 3. So you give it an OpenAPI file, it’s going to spin up the mock server, which is going to behave exactly the way you specify it. And so you can give it to your front end developers and they can start crafting the UI.
I’m going to be showing just no more than two or three examples. And then I’ll hand it over.
So I have already in OpenAPI 3 file, OpenAPI 2 and 3. We do support both in Spectra and Prism. And so I can say:
samples/pet-store/OpenAPI3.json"
And so it’s going to analyze my file and it’s going to spin up the mock server. And it’s telling, according to your OpenAPI files, this is the options that you’re offering. And so I can simply do:
http://localhost/4010/pets/10
You’re going to get a response. But more importantly, one of the things that I think is important is you’re going to get to the logging, which is going to tell you: “I received these requests. This is the error that I got. The validations rule have been passing. I found a compatible content. This is what I’m returning to you.”
And you can do this multiple times and you can see that the example is static, which is okay to a certain point. But what we also did, we implemented a dynamic example generator. And so if you pass the minus the flag, it’s going to say “dynamic examples enabler.”
And so every time I do this, I’m going to get a different response, according to the scheme anyway. And so this is going to help your developers to encounter edge cases so they don’t get stuck with the static example. Like if the name is going to be fluffy for every time, they’re going to probably sides the UI somehow. But if forget the different thing every single time, a valid example anyway, maybe they’re going to encounter edge cases ahead of the time and prepared accordingly.
Another thing we can do, which is also, I think I recall, is we validate the payloads. And so for example, if I do:
pets/findby/status
So this request—in particular—has a schema for the request body. And so prism has been checking it out, didn’t pass the validation has been trying to find the final average response, 42, they don’t find it. Genetic 400: didn’t find. And then I’m going to craft the response for you. And that’s what I got back. We made this response because the query parameter with the code parameter is not okay. And then I can probably simply fix this.
Status=sold
But just to show what is going to really help you here. If I cancel this and I … Yeah. You can see why prism has responded you in such a way. Because it was trying to find this response. I didn’t find it. I found this other one, but it wasn’t good enough. And then I fall back to the error. And so if you don’t understand why prism respond in such a way. You can see the logs and you’re going to follow the flow. And we have also other bunch of features that contract validation. We can generate payloads in XML, JSON as long as your OpenAPI specification supports it.
And you can give this server to your front end developers and they can try it on the spot, start to craft the UI, give it the feedback and you didn’t write any code. And so making the change is actually cheap. To make a full request of the document in your GitHub repository, Spectral is going to check that it’s okay with your internal policy. You merge it, the Prism server is going to be updated. You’re good to go for another round of iteration.
So I think this is going to hopefully help you to move forward and faster—it is all OpenSource.
View the full video from Vincenzo’s demo.
Want to learn more about APIs?
Join us for our next meetup!
About Author
Leave a Reply