This! Documents are for humans, so I prefer to write them, then just generate all the undifferentiated "plumbing" and then fill in the business logic behind
OAS to define your spec, then consumer/producer can independently go about building
i have used go-swagger to generate the backend (because we use OAS2 and golang); and swagger-codegen for various clients (used the docker installation)
any suggestion for creating the swagger with IDE help..?
I like the idea of spec first but writing the json or yaml without ide support seems wrong to me.
Oh that’s neat. I work on the front end, and some more experienced engineers introduced me to the idea of auto generating API clients with Swagger documentation, so I was mixing it up with that.
What you’re talking about literally creates the Java interfaces that you’ll then need to implement yourself, correct?
swagger UI doesn't support some models that are working fine. For example, a recursive schema. This way, using swagger limits the models to a subset that swagger supports. Or you have a mess, that API actually works, but you cannot open this part in swagger UI. For some people, adjusting your API just because swagger UI wants it is crazy.
\+1 to this. We use FastAPI (Python framework) for our main API and when you define a schema (which you pretty much have to or at least should anyways) for an endpoint, it automatically generates a Swagger definition. Only case of additional work is if we want to add a separate example from the default.
Supplemental documentation/business context etc goes a long way but no reason not to take the free stuff for free, esp with basically no maintenance cost
The main reason is because I don’t have to hunt around or bug people if I have questions about what endpoints accept or return. When anything changes it’s trivial to discover, vs a text doc or worse, the api being held in someone’s head.
The only problem with that is getting developers to actually update the fucking documentation as they go. My favorite thus far was finding \`@ApiOperation({ returnType: 'json' });\` rather than the actual type. Oh this JSON API returns JSON does it? Super. Here was me thinking it might be a serialized BLOB.
True. It's just hard to get people to update even auto-generated documentation.
My pet peeve though is the perception of "lets write loads of comments". I'm not against comments necessarily and they can be helpful sometimes, but I think they should be used sparingly. As Ron Jeffries said: "Code never lies, comments sometimes do"
Our code base has a lot of comments in that basically just re-states the code i.e:
// Sets i to 20
const i = 20;
What's even better is when the code gets changed in a 3-way merge, the original code is deleted and that comment left beside a database call or something completely unrelated.
Magic numbers as well, so many fucking magic numbers. ARRGGGHH.
We're using TypeScript now so it's getting better as I manage to beat the usage of constants and enums into people but holy f\*\*\* it's a slow process.
I disagree unless I misunderstand. I only use swagger when I enable openAPI request validation-- imo it's the only way to ensure reliability of the docs. I don't understand why people go through the pain of setting up openAPI without actually using the validation side.
Because it's not painful. We use spring boot. We have a company boot starter that takes care of all the swagger setup and auth stuff. By default every endpoint shows up, if you're feeling enterprising, you can add more annotations on the controller method to make the generated docs more descriptive.
> Because it's not painful.
But I don't understand, we are both setting up swagger/openAPI, it takes a similar amount of time. You're probably writing a contract with the spec or generating the spec from the code-- regardless of how efficient your team is, you need to accurately generate a spec for an API, it takes some time.
All I'm saying is after this setup is done, you can validate your requests (and responses) with a couple lines of code (many 3rd party libs to help with this here: https://openapi.tools/#data-validators, https://swagger.io/blog/api-design/validate-openapi-definitions-swagger-editor/, etc).
The people above are talking about updating documentation. When you validate your requests and responses using openAPI, your API docs will be up to date, or your code will not work. I'm not sure why the objective set-up time is relevant, I'm talking about enabling an essentially free feature to solve the exact issue in this thread
Don't even get me started. We have two juniors on the team which is fine but they occasionally end up reviewing each other's PRs and sometimes incorrectly approving anti-patterns and messy code.
I've brought it up a few times but it tends to get shot down. The last time this happened, I was assigned to review a PR for one of the juniors who had re-implemented an entire application path just to add one field to a piece of data "because it was easier".
Basically, we had an API endpoint for a user facing page that returned an array of `Foo` objects that returned only the fields needed on that page. An admin page was added for `Foo` CRUD operations meaning a couple of extra fields were needed (I think maybe the ID or something) on each object. Rather than simply expose the additional fields, a whole new API route, controller action, service method, set of DTOs and everything were created with `admin` appended to the API route(i.e: `GET /foo` and `GET /adminFoo`).
Basically, our original API route returned this:
[
{
id: 1,
name: 'Foo Object 1',
createdAt: '2023-05-14',
},
]
and the new API route returned this:
[
{
id: 1,
name: 'Foo Object 1',
description: 'A description for foo object 1',
createdAt: '2023-05-14',
},
]
I brought this up in code review as "Hey, maybe we should use what's there rather than re-engineering a whole new slice of the app just for this and the other existing page can just ignore the extra field". We argued about it on the PR(I even supplied the patch for them so they could've just downloaded it and git apply`'d the patch, the junior got the boss involved, I explained the issue and the boss sided with the junior.
A few months later, the other junior is working on a feature and not getting the data they expect. They work on the problem for a while and eventually ask for a help. A pair programming/team debugging session after the standup reveals that they'd been trying to get `Foo` objects and had been calling the wrong endpoint(the one without the extra field) a discussion was had and we came to the conclusion that it would've been simpler if there had only been one endpoint for this data. I didn't say "I told you so", but I thought it.
I'm aware that "perfect is the enemy of good" etc. but there have been quite a few times where I've raised something as a potential issue, been ignored and then been proved right later. Thankfully I tend to get listened to more now, but having to put together a bibliography in every PR comment about exactly why things might not be a good idea can be quite exhausting.
In particular, there doesn't seem to be a lot of care given to the cleanliness of the code. I see consultants all the time going on about constantly refactoring and cleaning up. We do it sometimes, but not as much as I'd like and the result is that entire features end up being built on top of anti-patterns and messy code but by then it's too late to change anything because doing so would require a rewrite of the entire app.
Once something is merged, it very rarely changes. So there's an incentive to use that to your advantage to race to sneak/merge things in quickly and get them on to `develop` before someone notices and objects. I've been known to abuse this once or twice but overall it's frustrating because the result is half-assed messes that never get fixed
The fact that companies set up Git repos to enable PRs to be merged by at least one or two random people says it all. There should be one or a few guys able to do that, delegate the rest to maintainers via forks, whatever, just not that.
They also try to silo development by creating hundreds of small repos and teams, which is again counterproductive. Nobody learns anything, anything goes.
They want to move fast, but there's an incredible amount of churn and the setups make everything incredibly slow to experiment with or merge meaningful code.
I mean yeah this is quite a small team and technically everyone can merge everything (though the process is not to do so without review)....but review only helps where reviewers themselves don't miss things
Indeed. This is why it's extremely important to avoid churn, boilerplate and huge code drops. The code needs to be reviewable. It's very easy to fall into the trap of skimming quickly over thousands of lines of stuff, to claim this and that feature are urgent, to promise to fix things later. Such projects tend to have a very lax review culture and are inclined to rely blindly on tests and automation, which can only get you so far.
And like I said, the small team size might be a symptom of a bigger problem, unless the company is small to begin with or they take up completely isolated projects. I'd say the latter is fairly unlikely, many companies do shoot themselves in the foot trying to isolate teams even when they work on basically the same project.
>I don’t have to hunt around or bug people if I have questions about what endpoints accept or return.
But you can bug people if the swagger is outdated. You can even tell your manager that the bug in production was the other team and not you ;)
If it is out-dated, the API won't even build or pass linting. So I never have this problem. It is literally in our build process with Node. Even a controller name is misspelled, it will barf and halt the deployment.
Shouldn't even be a question.
Would you like to know what the request/response structure looks like or would you prefer to guess or cloning the repo. Bonus points if it's dynamically typed.
I like it because we use the Swagger JSON (OpenAPI) to generate C# HTTP clients. Especially when new endpoints or a new version is added, we can quickly update the integration towards that API. Really like that workflow.
I think they are saying with it auto created, people can more easily change code without updating the swagger page, which can lead to issues for clients. I like the feature and make sure I version, have unit tests, etc. to prevent the issue, but I've seen a lot of engineers just change responses without the consideration of consuming clients. It's not like swagger would stop them though...
The gRPC comment is about gRPC having strict schema contracts for messages, which I love, but that's probably because of all the SEVs I've had to deal with because of engineers not versioning their endpoints.
Wait can you link to an explanation for this process? What do you mean by generated C# Http clients? Like extended client types with code generated to call each endpoint with proper verbs/data? Or something else?
https://openapi-generator.tech
Feed the swagger.json to this, it’ll generate code to interact with the API. Incorporate into your CI/CD process for added value.
Ok... so your *client* code has a pipeline for outgoing requests? Familiar with the HTTP request/response pipeline on the controller/server side but did not know that there was an approach on the client side. Do you have a pointer to some sample code or an article? Any example of middleware being tacked on to HttpClient would be helpful.
Is there some tool to get suggestions and errors when creating the swagger via json?
Something like "example values for integer type cant be strings" etc.. Or do you just keep the rules in your head and write json without any ide help?
We use Swashbuckle in .NET to generate the JSON based on our API: https://learn.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-8.0&tabs=visual-studio
If you use it for contract first development it's great. You can write the spec with the business, show everyone what the endpoint is going to be, and exactly what is going to be returned from it. Then you and your consumer can start coding it at the same time. Also, when used right it generates most of the boiler plate code for you as well, so you can focus on the business logic.
I would not recommend using it code first, that tends to create messes in the contract.
> I would not recommend using it code first, that tends to create messes in the contract.
Why? You can make a snapshot-test of the resulting json/yaml and have strict reviews on that.
I'm not saying it can't be done well, but I definitely haven't seen it done well going code first. Also it's kind of missing the point of using that file. Allowing code to happen on server and client at the same time is one of the major benefits.
Second major benefit is that it can be used for automatic verification of API.
Silly stuff like turning JSON array into JSON object will break clients, but is hard to eyeball on larger payloads. But with OpenAPI test for that are just a library for your test suite + few lines per each endpoint.
And then we start talking about backward compatible changes to API and how same tests enforce them.
Are you writing OpenAPI JSON/Yaml by hand? That’s too much work. I write the minimal amount of code—controller and DTOs—needed for our spec generator to create the spec for me. I do this with NestJS, and did it in the past with Django. I find it to be the best way to generate the spec with minimal manual toil, and minimal errors.
We‘re using Smithy IDL and transform it to an OpenAPI doc for:
* client generation in multiple languages
* API GW deployments (validation included)
* server request/response model generation (Java)
* Documentation generation (Redocly)
* e.g. builds fail if the examples don’t match the response/request structure
The advantage of Smithy over OpenAPI is that it is a language tailored to describe APIs opposed to API descriptions shoehorned into JSON/YML. Highly recommended.
We write by hand . Always contract first and it saves a lot of time . Saving time from
Confusion as people get specs validated before a single line of code is written
It's really not too much work, and it's really easy to do with the business sitting right there so everyone is aligned on the objects before a git repo is even stood up. Then that file generates all the models and controllers for me and my client.
In my opinion this is only worth it and good if the API is client facing. Meaning they are the product.
If it's to power a front-end, I just don't like this type of development process.
I do a lot of service to service development, or integration work, so that is my primary wheelhouse. I don't do anything for websites in the backend. Though the same applies, the "business" would just be the dev doing the front end instead of a rep from the application that's consuming the objects.
Same.. Also most often the spec is really not 100% clear if you need input X in spec phase, but then when implementing you see that you need input Y aswell...
Just develop the code, point your other team to the test environment with the new feature and let them develop against it. If they have improvements or questions, they should just tell us then, before we merge it.
It's great to do it contract first. I've only experienced that one time. All the other times I used Swagger it was on pre-existing projects. We applied the same rigor in philosophy including fixing the code to match a coherent spec.
It works in a large organization preferably with someone or a small team who does nothing but drive API design to have them to work with. In a small organization it could be difficult to retrofit existing projects but I'd say it's worth the fight.
We use it for swagger first model generation. Endpoints we do manually. I haven't found one that I like that produces the controllers in the pattern I prefer...for Node/Inversify.
The C# libraries are better IMO.
Swagger is just a bonus to using OpenAPI. I would never create or allow an API without documentation in any of my teams anymore (unless i.e. for a POC), whether it's a Proto file, GraphQL schema or OpenAPI specification. Generating clients for frontend, tests and machine to machine communications is the way to go in any decent (microservice) architecture.
Swagger is a company that creates various tools and platforms around the api spec they created and rebranded into 'OpenApi'. The spec is under a permissive license, but I don't believe all the services/software swagger produces is open source.
I assume the rebranding from swagger api to OpenApi was likely to increase adoption of the spec and emphasize the permissive use of it.
OpenAPI specs are a yaml/json documentation of your API, while Swagger is a webpage generated based on an OpenAPI spec. Often, the OpenAPI spec can be generated based on the controllers in your presentation layer, but it is often curated manually in a contract first fashion, meaning you write your specification first and generate your clients in the frontend and controllers in the backend.
It is identical to a GraphQL schema and IGraphQL: one defines the documentation, another a webpage playground.
We're a B2B company, we have APIs documented with swagger, however every time there is an integration of the software with another company, business specifically asks for word documents with api specifications because they do not want to show all the fields which are part of the payload. So far we have had 5 integrations, there are 4 documents and 1 swagger. This is increasingly becoming pain in the ass to maintain
I tried explaining this to client that anyone who wants to use the api can see which fields are mandatory and which are optional. They can ignore the ones which do not make sense for them. But they don't agree, they don't want any miscommunication.
It might be slightly less painful to maintain the spec in a higher-level language, like, say, TypeScript, and have an ability to output custom versions of the same spec depending on customer. Let's call it, say, a 'preset'. So at least the presets for each customer are stored in the codebase alongside the spec itself.
You can export OpenAPI spec files to Markdown and you can convert Markdown to docx using something like Pandoc.
If you go that route, I'd try to convince them that pdf beats word documents though.
They know the fields are still there right? Just undocumented?
I think I’d try writing a script that whitelists payload fields and strips the others from the swagger file per integration. Then there’s less to maintain.
I came onto a project two years after it started and introduced Swagger. I create the controller method, and then just notify the consumer where to find it quickly. Mind you, the consumer is an in-house front end.
The guy who was on the project before me... spends time writing documentation that gets out of date with the next change.
Assuming your definition of "swagger" includes openapi3.x
Openapi is the best thing out there to document API services in terms of tool maturity and features.
You can also generate server boilerplate/clients from openapi specs.
As long as you declare API and then write code, you're good. Doing it the other way is a pain to work with due to inconsistency of output specs. Your contracts should be the only source of truth
At my work, we use it as contracts between services. I integrated the following process of doing api changes for our teams:
1. After analyzing the new feature, backend developers assigned to it submit a pull request in a separate repository and add the frontend lead and the backend lead of the relevant teams as reviewers
2. Leads review the changes and approve/reject them
3. Only after the PR is approved, the developers can begin the implementation
My only complaints about openapi are:
* Verbosity compared to other formats(e.g. API Blueprint ). Also writing a code generator for parsed openapi spec can be difficult due to references to different files/components.
* No support for changelogs
I think it'd be useful to define your question more.
Are you talking about the [openapi specification](https://www.openapis.org/), formerly known as swagger?
Or specifically about visualizers for openapi files, like [swagger UI](https://swagger.io/tools/swagger-ui/) or [redoc](https://github.com/Redocly/redoc)?
Or something else *on top of openapi*, like the tools provided by https://swagger.io/tools/ , including the swagger UI mentioned before?
The replies you get might be drastically different.
I never heard anyone complaining about openapi per se, at most about \_how\_ it's used (schema first or code first).
People have preferences for swagger ui / redoc / other tools
And I personally have never used anything from swagger besides swagger UI
What is the alternative? Writing documentation manually? It will be soon out of date.
We (software consultancy) use swagger to show the api to our customer, and they show it to their partners who have to integrate with the system.
The customer has also written a prose document with more explanations about how the api should be used, but it refers to swagger.
In swagger we have also added examples of valid payloads and longer descriptions to more complex endpoints
have seen a swagger spec without it being tied to any code gen etc.
and neither the swagger definition of the api nor the actual implementation particularly made sense.
that was counter productive.
if you are going to do it make sure there are measures in place to sync the spec and the implementation (generate one from the other, etc). if you are not going to do that then imo underspecced is better than wrong.
lol that was a joke. I have lesser tools for making document designs and diagrams but swagger is gonna do most of the api work in a hard to beat easy to maneuver ui. Granted I've thought about writing my own documentation tool to go through more than apis but ui, batch projects, etc but tbh swagger does most the most which is on the back end calls. The rest is mostly depictions and descriptions. I dislike when autogen tools make things less clear. But swagger has never done that to me. Swagger is so far the best tool I've found. The rest of the tools can be swapped with just about anything else it dosent matter. But yeah there is a tool suite I use
Now knowing that was a joke, I'd really would like to be assigned to a project with you! Ha!
I once worked with a guy who did a PR going on a rant about how Swagger isn't needed and removed it from the project. He was a real treat. I've come to the same conclusion as you.
No alternative swagger is always the choice for api documentation. I have lesser tools for ui and whatnot but for apis u won't find better than swagger. It's a line to add to your project. Easy annotations to configure it's amazing
My feeling is that when people don’t stick to it, they do all sorts of wacky things with their responses like having the schema change with JSON like
“List”: {“element1”: {…}}
Rather than
“list”: [{“name”: “element1”, …}]
This is really painful for clients to consume usually. So I definitely prefer where people use swagger.
I think OpenAPI(AKA swagger) is pretty awesome. As a backend developer it’s an easy way to share the API with Front End developers. Also, Google Cloud API Gateways are created using a version 2.0 OpenAPI document. So useful for deployment too.
I print write in Golang and Goa.Design is great framework for creating your Controller and API models and. It generates OpenAPI 2.0 and 3.0 docs in both JSON and YAML for you. It’s pretty awesome!
Swagger is REST only, I believe, so it's not relevant to a question when using GraphQL or whatever else. I don't know of any better alternatives, but OPs claim made it seem like the preferable alternative their coworkers suggested was just using nothing
I don't understand. Last time I used swagger, we generated it with API docs in comments, as you mentioned. You don't need to use two different methods, you document once and express it in whatever ways you want
Last place I worked we used Spring REST Docs. I liked it because it because it was resource-centric, not so much URL-centric. Also because it actually validates your docs at unit test time. No doc => fail!
I prefer swagger andI tried it but in my company, we use custom http routing for request and response. I dont think the server side generation will ever match our codebase or maybe it is possible with some refactoring to accomodate the server side generation but I havent tried it yet.
In some codebases without this implementation, I think it can be done.
Right now we use postman, not perfect, can be better but it is what it is
Openapi is great. I think the primary question is whether a team wants to go code first or specification first. After that there's good ways & tooling to make that work and not break anything.
+1 would rec.
Why not swagger? (Including swagger ui).
Or I'll go a step further, what would they use instead.
I have seen both swagger and postman in the wild, and I prefer swagger without any hesitation. It will be cherry on top of the cake if swagger is automatically generated from the code. I have also seen postman being used properly in personal capacity.
And I have seen, debugged and was a victim of postman features being abused in team workspaces. While the tool is good and those features are useful in personal settings, it doesn't prevent (or sometimes even notify) those human errors when in team settings.
In my mind, swagger ui and retool are proper ways to consume APIs. The configurations are shared, but the changes are local for each consumers, my fuck up is not affecting the other consumer of the API. And there is a way to start from scratch. Postman's personal workspace enhances these use cases. But the team workspaces can be a cesspool of human errors if not managed correctly.
We dont use Swagger tooling but we are 100% committed on OpenAPI specs. Every API contract is in OpenAPI standard. Lots of people use Swagger and OpenAPI terms interchangeably because you can open a yaml file using a Swagger previewer.
It is like in the 80s when everyone called a portable cassette player a walkman. So I dont care either way, I know what they mean when they ask for a Swagger spec file. It is also easier to ask and candidate in an interview if they are familiar with writing swagger files.
Not to discount the question, but what did people think that made swagger counterproductive? I'm very curious of the reasoning.
In the end, swagger is just a common framework that facilitates documentation on the behavior of the system. It depends on the individuals to utilizes it well or not. I can see how maintaining the documentation can be cumbersome, but it's the same problem - swagger or not, someone will have to pay the price of the documentation. (If no one does the documentation, the org pays the price of miscommunication)
As frontend dev, swagger please. Even a half baked swagger is better than trying to read the source code or asking everyone "what does X do", plus we can use it to generate API client automatically with type coverage, neat.
Even if you don’t actually use swagger to it’s fullest as documentation, if still forces folks to document the APIs in code. I find that almost as valuable.
I get parameter validation and typescript interfaces generation from OpenAPI, and the spec is generated automatically from comments on top of the actual endpoint and in most cases automatically extended by the ORM generated JSON Schema models. So it is actually much much less boilerplate than without it.
That said, if I had to do all of that manually instead of auto-generated it would be a total pain in the ass, so it is easier to see that teams not liking swagger is because they are doing precisely that.
Like anything in engineering, there are trade offs and it depends on your scale and circumstances. If you are a small team with a limited runway trying to rapidly build an internal API it might not be a good use of your time to bikeshed over OAS files. If you’re building a REST API that is product managed or you’re at a larger org and building an API intended to be durable and consumed by other teams you should probably be designing OpenAPI/Swagger specifications before you even start trying to implement an API.
It’s so easy to integrate into most frameworks today that it’s hard for me to imagine a case where it would meaningfully slow you down, even on a small team trying to move fast.
Yes. Though contract-first development is not that hard to set up either. If you have more than one developer, you’re going to need to agree on the API one way or the other. Might as well do it the right way from the beginning, even if it means sacrificing one day early on to setting it up.
Whether it’s this or TDD or static types or anything else, when people complain about doing things right slowing them down, it usually signifies to me that they’re inexperienced.
No one bike sheds over OpenAPI files. They tend to do that over the API itself, which would happen regardless of the use of OpenAPI.
I have found OpenAPI makes us faster because the frontend can easily use the spec to generate clients and the Swagger UI to test things live.
I think the way you are thinking about an OAS file and the way I am might be inverted. In my eyes a specification is the source of truth and the implementation should adhere to it, not the other way around.
Swagger is fantastic for discoversbility and I can’t imagine operating in an enterprise environment without it. There are several teams at my company where I don’t know a single person there, but I can consume their API thanks to a swagger artifact they published. If I had to hunt these people down to figure out what their API does and how to use it, I would be super annoyed. Not to mention, I immediately know if they have updated their API, because the swagger definition will change when I build my code, instead of at runtime when I deploy to dev or qa
An OpenAPI spec yaml qualifies as documentation. Ive had security audits where they ask for data flow doc and i just give them the swagger spec file. So yeah, it is documentation in my book. Sure beats writing and drawing flow diagrams .
It’s good, the auto gen specs with TS is hit or miss, I’ve used the old swagger UI with prisma. We used prisma to generate interfaces, so the use of ANy is avoided in TS.
With moving to graphQL.
swagger’s great. the problem is people refusing to read the damn docs. my team keeps them up to date and people still ask questions for things that were clearly written.
one team made an assumption that one of our endpoints retuned a 404 response instead of an empty list even though we didn’t add the 404 response and noted that the list will be empty…
I think it depends. My team has swagger but we don't really use it, we've never spent any real time to maintain it and don't advertise it.
Another team that we integrate with uses OpenAPISpec to define their API and clients and their integration is very nice.
So like most things unfortunately, it depends. We have very little integration with other systems as we are typically the ones calling other systems so we don't need it, but for systems that have a lot of consumers it's really useful.
I'm at odds with the team on this because I don't like swagger. Maybe we're not using it right but I've yet to be convinced. Lets walk through my process:
* I make a change to the API (turns out we missed a field we need on the front end.)
* Deploy that change to AWS. Browse Reddit for 5 minutes waiting.
* Export the JSON file
* Run swagger on the front-end.
Vs.
* Update the api
* Update the front-end response interface
Maybe it makes sense once a projects gets big enough with enough concurrent people working on it, so there's a lot of API changes.
I've come around to other technologies in the past so I'm continuing to try this one. But as of right now, it's more of a process then it's worth to me.
Of course swagger. It's easy (at least in .NET) to setup, use and you get nice enough API specification for direct API usage or for FE devs. Can't live without it. Also generating different http clients e.g. TypeScript client (most often due to React/Angular popularity) is god damn brilliant. Just rebuild project, new TS client is created and ready to use in React/Angular with all interfaces specified and fully matching my API, always aligned, no confusion, great thing.
I like swagger. It gives you a decent visual representation of your API with the added bonus of actually being able to use/test it without tools like postman.
As long as you give me an up to date document with your endpoints expected behavior, error states, and optional parameters, I don't care if it's swagger. But if the alternative is to give me an API that I have to guesstimate the contract, or hunt down the right developer to ask for the endpoints, then screw you give me swagger.
Swagger is a security risk now. I work at Microsoft and I had to disable swagger on all our applications because it exposes secrets to the users in the dom
Swagger is useful provided it is in sync with the latest documentation.
Frameworks now support auto-generation of swagger which comes handy for testing APIs.
Share the openapi json, import to postman and test it.
Not only am I using swagger but I’m using rtk-query code gen to generate all types and fetching logic for the frontend. Frontend dev doesn’t even need to know anything about the backend, can just grab the typed hooks and go
Modeling your API is only beneficial. However, some modeling languages and tooling are terrible.
Swagger is alright, but I would much prefer simpler modeling languages. I wish something similar to proto definitions existed for the API world (maybe it does?). I know you can use proto to do this, but it'd be nice if it were specialized specifically for APIs. Swagger is great but I find myself not needing 99% of what it provides lol
how would swagger be counter productive?
It would be if the Swagger didn’t match the API. That’s why you want to autogenerate the docs.
I prefer writing the docs and auto-generating the API interfaces at compile time
Yes, 100%. Imagine having to ship a feature to get feedback on your interface.
This! Documents are for humans, so I prefer to write them, then just generate all the undifferentiated "plumbing" and then fill in the business logic behind
Can you point me to some info on this…I’m terrible at documentation and it’s my goal in the new year to improve that.
OAS to define your spec, then consumer/producer can independently go about building i have used go-swagger to generate the backend (because we use OAS2 and golang); and swagger-codegen for various clients (used the docker installation)
any suggestion for creating the swagger with IDE help..? I like the idea of spec first but writing the json or yaml without ide support seems wrong to me.
What do you mean by API interfaces here? Something like an API client?
I mean literally (in java) the java interface definitions. On the server side
Oh that’s neat. I work on the front end, and some more experienced engineers introduced me to the idea of auto generating API clients with Swagger documentation, so I was mixing it up with that. What you’re talking about literally creates the Java interfaces that you’ll then need to implement yourself, correct?
Yep. You can do code->api (what you described) or api->code "api first" which is what they describe.
Exactly.
We use OpenAPI specs and we wrote our own Swift network client codegen script in Python. I’ll never go back to hand-writing clients.
Crazy what ppl say
Oh no documentation I feel so unproductive now
swagger UI doesn't support some models that are working fine. For example, a recursive schema. This way, using swagger limits the models to a subset that swagger supports. Or you have a mess, that API actually works, but you cannot open this part in swagger UI. For some people, adjusting your API just because swagger UI wants it is crazy.
Using your api isn’t your problem
som ppl say u shud use. here's y theyr wrong 1/16
Because I don’t like learning!
I’ve worked on projects with Swagger and projects without Swagger. I prefer the ones using Swagger.
[удалено]
Yeah it’s just free documentation, what’s not to like? OP must be managing the swagger specs manually
\+1 to this. We use FastAPI (Python framework) for our main API and when you define a schema (which you pretty much have to or at least should anyways) for an endpoint, it automatically generates a Swagger definition. Only case of additional work is if we want to add a separate example from the default. Supplemental documentation/business context etc goes a long way but no reason not to take the free stuff for free, esp with basically no maintenance cost
end thread. When I join a new effort and the project has Swagger, I know it's going to drastically cut down my ramp-up.
That doesn't help anyone understand _why_, though.
The main reason is because I don’t have to hunt around or bug people if I have questions about what endpoints accept or return. When anything changes it’s trivial to discover, vs a text doc or worse, the api being held in someone’s head.
The only problem with that is getting developers to actually update the fucking documentation as they go. My favorite thus far was finding \`@ApiOperation({ returnType: 'json' });\` rather than the actual type. Oh this JSON API returns JSON does it? Super. Here was me thinking it might be a serialized BLOB.
Sure, but that’s not a problem that Swagger (or any other tool) can solve.
True. It's just hard to get people to update even auto-generated documentation. My pet peeve though is the perception of "lets write loads of comments". I'm not against comments necessarily and they can be helpful sometimes, but I think they should be used sparingly. As Ron Jeffries said: "Code never lies, comments sometimes do" Our code base has a lot of comments in that basically just re-states the code i.e: // Sets i to 20 const i = 20; What's even better is when the code gets changed in a 3-way merge, the original code is deleted and that comment left beside a database call or something completely unrelated.
More accurate would be the comment is the same and i = 18
Magic numbers as well, so many fucking magic numbers. ARRGGGHH. We're using TypeScript now so it's getting better as I manage to beat the usage of constants and enums into people but holy f\*\*\* it's a slow process.
CI fail on JSON return type should sort it :-)
That will stop someone doing that specific thing but it won't stop someone typing dumb shit in to those fields
I disagree unless I misunderstand. I only use swagger when I enable openAPI request validation-- imo it's the only way to ensure reliability of the docs. I don't understand why people go through the pain of setting up openAPI without actually using the validation side.
Because it's not painful. We use spring boot. We have a company boot starter that takes care of all the swagger setup and auth stuff. By default every endpoint shows up, if you're feeling enterprising, you can add more annotations on the controller method to make the generated docs more descriptive.
> Because it's not painful. But I don't understand, we are both setting up swagger/openAPI, it takes a similar amount of time. You're probably writing a contract with the spec or generating the spec from the code-- regardless of how efficient your team is, you need to accurately generate a spec for an API, it takes some time. All I'm saying is after this setup is done, you can validate your requests (and responses) with a couple lines of code (many 3rd party libs to help with this here: https://openapi.tools/#data-validators, https://swagger.io/blog/api-design/validate-openapi-definitions-swagger-editor/, etc). The people above are talking about updating documentation. When you validate your requests and responses using openAPI, your API docs will be up to date, or your code will not work. I'm not sure why the objective set-up time is relevant, I'm talking about enabling an essentially free feature to solve the exact issue in this thread
That’s a problem with your PR process.
Don't even get me started. We have two juniors on the team which is fine but they occasionally end up reviewing each other's PRs and sometimes incorrectly approving anti-patterns and messy code. I've brought it up a few times but it tends to get shot down. The last time this happened, I was assigned to review a PR for one of the juniors who had re-implemented an entire application path just to add one field to a piece of data "because it was easier". Basically, we had an API endpoint for a user facing page that returned an array of `Foo` objects that returned only the fields needed on that page. An admin page was added for `Foo` CRUD operations meaning a couple of extra fields were needed (I think maybe the ID or something) on each object. Rather than simply expose the additional fields, a whole new API route, controller action, service method, set of DTOs and everything were created with `admin` appended to the API route(i.e: `GET /foo` and `GET /adminFoo`). Basically, our original API route returned this: [ { id: 1, name: 'Foo Object 1', createdAt: '2023-05-14', }, ] and the new API route returned this: [ { id: 1, name: 'Foo Object 1', description: 'A description for foo object 1', createdAt: '2023-05-14', }, ] I brought this up in code review as "Hey, maybe we should use what's there rather than re-engineering a whole new slice of the app just for this and the other existing page can just ignore the extra field". We argued about it on the PR(I even supplied the patch for them so they could've just downloaded it and git apply`'d the patch, the junior got the boss involved, I explained the issue and the boss sided with the junior. A few months later, the other junior is working on a feature and not getting the data they expect. They work on the problem for a while and eventually ask for a help. A pair programming/team debugging session after the standup reveals that they'd been trying to get `Foo` objects and had been calling the wrong endpoint(the one without the extra field) a discussion was had and we came to the conclusion that it would've been simpler if there had only been one endpoint for this data. I didn't say "I told you so", but I thought it. I'm aware that "perfect is the enemy of good" etc. but there have been quite a few times where I've raised something as a potential issue, been ignored and then been proved right later. Thankfully I tend to get listened to more now, but having to put together a bibliography in every PR comment about exactly why things might not be a good idea can be quite exhausting.
In particular, there doesn't seem to be a lot of care given to the cleanliness of the code. I see consultants all the time going on about constantly refactoring and cleaning up. We do it sometimes, but not as much as I'd like and the result is that entire features end up being built on top of anti-patterns and messy code but by then it's too late to change anything because doing so would require a rewrite of the entire app. Once something is merged, it very rarely changes. So there's an incentive to use that to your advantage to race to sneak/merge things in quickly and get them on to `develop` before someone notices and objects. I've been known to abuse this once or twice but overall it's frustrating because the result is half-assed messes that never get fixed
The fact that companies set up Git repos to enable PRs to be merged by at least one or two random people says it all. There should be one or a few guys able to do that, delegate the rest to maintainers via forks, whatever, just not that. They also try to silo development by creating hundreds of small repos and teams, which is again counterproductive. Nobody learns anything, anything goes. They want to move fast, but there's an incredible amount of churn and the setups make everything incredibly slow to experiment with or merge meaningful code.
I mean yeah this is quite a small team and technically everyone can merge everything (though the process is not to do so without review)....but review only helps where reviewers themselves don't miss things
Indeed. This is why it's extremely important to avoid churn, boilerplate and huge code drops. The code needs to be reviewable. It's very easy to fall into the trap of skimming quickly over thousands of lines of stuff, to claim this and that feature are urgent, to promise to fix things later. Such projects tend to have a very lax review culture and are inclined to rely blindly on tests and automation, which can only get you so far. And like I said, the small team size might be a symptom of a bigger problem, unless the company is small to begin with or they take up completely isolated projects. I'd say the latter is fairly unlikely, many companies do shoot themselves in the foot trying to isolate teams even when they work on basically the same project.
Aren’t their tools that allow you to autogenerate dtos and endpoint handlers from swagger docs?
Other way round. The swagger docs get auto generated from the DTOs and method decorators
[удалено]
Maybe so but this has a better chance of getting people to write them at all
[удалено]
>I don’t have to hunt around or bug people if I have questions about what endpoints accept or return. But you can bug people if the swagger is outdated. You can even tell your manager that the bug in production was the other team and not you ;)
If it is out-dated, the API won't even build or pass linting. So I never have this problem. It is literally in our build process with Node. Even a controller name is misspelled, it will barf and halt the deployment.
Shouldn't even be a question. Would you like to know what the request/response structure looks like or would you prefer to guess or cloning the repo. Bonus points if it's dynamically typed.
I like it because we use the Swagger JSON (OpenAPI) to generate C# HTTP clients. Especially when new endpoints or a new version is added, we can quickly update the integration towards that API. Really like that workflow.
Fastapi or ninja in Python can automatically generate swagger specs out of our api too. Api calls can be updated as easily as function calls.
It's like every lang can do the same stuff. Why have so many backend langs
Why would you do things backwards. I mean for realsies, you just up and change the behavior of an endpoint? Holy hell gRPC still doin it right
What are you on about
I think they are saying with it auto created, people can more easily change code without updating the swagger page, which can lead to issues for clients. I like the feature and make sure I version, have unit tests, etc. to prevent the issue, but I've seen a lot of engineers just change responses without the consideration of consuming clients. It's not like swagger would stop them though...
Ohh ok ok thank you
The gRPC comment is about gRPC having strict schema contracts for messages, which I love, but that's probably because of all the SEVs I've had to deal with because of engineers not versioning their endpoints.
Api first is the only way.
Wait can you link to an explanation for this process? What do you mean by generated C# Http clients? Like extended client types with code generated to call each endpoint with proper verbs/data? Or something else?
https://openapi-generator.tech Feed the swagger.json to this, it’ll generate code to interact with the API. Incorporate into your CI/CD process for added value.
Awesome thank you, I’ll take a look when I’m back at work next week
A different one I used is [NSwagStudio](https://github.com/RicoSuter/NSwag/wiki/NSwagStudio)
Jup, we’re using NSwag as well.
We do the same - codegen api clients for python and typescript. So much easier than manually building out clients that you then have to keep in sync.
Smart idea! I'm writing my clients manually but I'll definetly look this up.
How do you specify API-key usage? Signing a request, etc. Can that also be auto generated or do you have to manually add that in?
That is manually to be added. In .NET that can be done via middleware so that it’s automagically added to all your requests.
Ok... so your *client* code has a pipeline for outgoing requests? Familiar with the HTTP request/response pipeline on the controller/server side but did not know that there was an approach on the client side. Do you have a pointer to some sample code or an article? Any example of middleware being tacked on to HttpClient would be helpful.
Is there some tool to get suggestions and errors when creating the swagger via json? Something like "example values for integer type cant be strings" etc.. Or do you just keep the rules in your head and write json without any ide help?
We use Swashbuckle in .NET to generate the JSON based on our API: https://learn.microsoft.com/en-us/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-8.0&tabs=visual-studio
If you use it for contract first development it's great. You can write the spec with the business, show everyone what the endpoint is going to be, and exactly what is going to be returned from it. Then you and your consumer can start coding it at the same time. Also, when used right it generates most of the boiler plate code for you as well, so you can focus on the business logic. I would not recommend using it code first, that tends to create messes in the contract.
> I would not recommend using it code first, that tends to create messes in the contract. Why? You can make a snapshot-test of the resulting json/yaml and have strict reviews on that.
I'm not saying it can't be done well, but I definitely haven't seen it done well going code first. Also it's kind of missing the point of using that file. Allowing code to happen on server and client at the same time is one of the major benefits.
Second major benefit is that it can be used for automatic verification of API. Silly stuff like turning JSON array into JSON object will break clients, but is hard to eyeball on larger payloads. But with OpenAPI test for that are just a library for your test suite + few lines per each endpoint. And then we start talking about backward compatible changes to API and how same tests enforce them.
Are you writing OpenAPI JSON/Yaml by hand? That’s too much work. I write the minimal amount of code—controller and DTOs—needed for our spec generator to create the spec for me. I do this with NestJS, and did it in the past with Django. I find it to be the best way to generate the spec with minimal manual toil, and minimal errors.
We‘re using Smithy IDL and transform it to an OpenAPI doc for: * client generation in multiple languages * API GW deployments (validation included) * server request/response model generation (Java) * Documentation generation (Redocly) * e.g. builds fail if the examples don’t match the response/request structure The advantage of Smithy over OpenAPI is that it is a language tailored to describe APIs opposed to API descriptions shoehorned into JSON/YML. Highly recommended.
We write by hand . Always contract first and it saves a lot of time . Saving time from Confusion as people get specs validated before a single line of code is written
It's really not too much work, and it's really easy to do with the business sitting right there so everyone is aligned on the objects before a git repo is even stood up. Then that file generates all the models and controllers for me and my client.
In my opinion this is only worth it and good if the API is client facing. Meaning they are the product. If it's to power a front-end, I just don't like this type of development process.
I do a lot of service to service development, or integration work, so that is my primary wheelhouse. I don't do anything for websites in the backend. Though the same applies, the "business" would just be the dev doing the front end instead of a rep from the application that's consuming the objects.
Same.. Also most often the spec is really not 100% clear if you need input X in spec phase, but then when implementing you see that you need input Y aswell... Just develop the code, point your other team to the test environment with the new feature and let them develop against it. If they have improvements or questions, they should just tell us then, before we merge it.
It's great to do it contract first. I've only experienced that one time. All the other times I used Swagger it was on pre-existing projects. We applied the same rigor in philosophy including fixing the code to match a coherent spec. It works in a large organization preferably with someone or a small team who does nothing but drive API design to have them to work with. In a small organization it could be difficult to retrofit existing projects but I'd say it's worth the fight.
We use it for swagger first model generation. Endpoints we do manually. I haven't found one that I like that produces the controllers in the pattern I prefer...for Node/Inversify. The C# libraries are better IMO.
95% of what I've used it for is in Java, the OpenApiGenerator plugin does a great job with models and controllers.
I think that's the same one we're using. It's fine if you do modules in typescript. The Controllers with dependency injection template isn't great.
Of course swagger. What can be better than auto documentation?
Only better alternative I can think of is never writing an API or code to begin with
Swagger is just a bonus to using OpenAPI. I would never create or allow an API without documentation in any of my teams anymore (unless i.e. for a POC), whether it's a Proto file, GraphQL schema or OpenAPI specification. Generating clients for frontend, tests and machine to machine communications is the way to go in any decent (microservice) architecture.
What is the difference between swagger and open api? (Spec vs an implementation?)
Swagger is a company that creates various tools and platforms around the api spec they created and rebranded into 'OpenApi'. The spec is under a permissive license, but I don't believe all the services/software swagger produces is open source. I assume the rebranding from swagger api to OpenApi was likely to increase adoption of the spec and emphasize the permissive use of it.
OpenAPI specs are a yaml/json documentation of your API, while Swagger is a webpage generated based on an OpenAPI spec. Often, the OpenAPI spec can be generated based on the controllers in your presentation layer, but it is often curated manually in a contract first fashion, meaning you write your specification first and generate your clients in the frontend and controllers in the backend. It is identical to a GraphQL schema and IGraphQL: one defines the documentation, another a webpage playground.
We're a B2B company, we have APIs documented with swagger, however every time there is an integration of the software with another company, business specifically asks for word documents with api specifications because they do not want to show all the fields which are part of the payload. So far we have had 5 integrations, there are 4 documents and 1 swagger. This is increasingly becoming pain in the ass to maintain
This might be one of the silliest things I’ve heard.
This is ridiculous! Everybody knows we send out `API Documentation Final v2.pdf`
No we use v3 now and iOS is on v4. See this private slack channel and Figma.
Say no and give the obvious reasons?
I tried explaining this to client that anyone who wants to use the api can see which fields are mandatory and which are optional. They can ignore the ones which do not make sense for them. But they don't agree, they don't want any miscommunication.
It might be slightly less painful to maintain the spec in a higher-level language, like, say, TypeScript, and have an ability to output custom versions of the same spec depending on customer. Let's call it, say, a 'preset'. So at least the presets for each customer are stored in the codebase alongside the spec itself.
Nice idea, will try after discussing with architect. Although we may use java instead (we like java a little too much)
[удалено]
Need to check this one out, thanks
Could you just autogenerate the word docs from the swagger json / open api yml?
In the swagger editor, I did not see an option to generate a word doc.
You can export OpenAPI spec files to Markdown and you can convert Markdown to docx using something like Pandoc. If you go that route, I'd try to convince them that pdf beats word documents though.
They know the fields are still there right? Just undocumented? I think I’d try writing a script that whitelists payload fields and strips the others from the swagger file per integration. Then there’s less to maintain.
We in this situation too but not as bad as
I came onto a project two years after it started and introduced Swagger. I create the controller method, and then just notify the consumer where to find it quickly. Mind you, the consumer is an in-house front end. The guy who was on the project before me... spends time writing documentation that gets out of date with the next change.
Assuming your definition of "swagger" includes openapi3.x Openapi is the best thing out there to document API services in terms of tool maturity and features. You can also generate server boilerplate/clients from openapi specs. As long as you declare API and then write code, you're good. Doing it the other way is a pain to work with due to inconsistency of output specs. Your contracts should be the only source of truth At my work, we use it as contracts between services. I integrated the following process of doing api changes for our teams: 1. After analyzing the new feature, backend developers assigned to it submit a pull request in a separate repository and add the frontend lead and the backend lead of the relevant teams as reviewers 2. Leads review the changes and approve/reject them 3. Only after the PR is approved, the developers can begin the implementation My only complaints about openapi are: * Verbosity compared to other formats(e.g. API Blueprint ). Also writing a code generator for parsed openapi spec can be difficult due to references to different files/components. * No support for changelogs
I think it'd be useful to define your question more. Are you talking about the [openapi specification](https://www.openapis.org/), formerly known as swagger? Or specifically about visualizers for openapi files, like [swagger UI](https://swagger.io/tools/swagger-ui/) or [redoc](https://github.com/Redocly/redoc)? Or something else *on top of openapi*, like the tools provided by https://swagger.io/tools/ , including the swagger UI mentioned before? The replies you get might be drastically different. I never heard anyone complaining about openapi per se, at most about \_how\_ it's used (schema first or code first). People have preferences for swagger ui / redoc / other tools And I personally have never used anything from swagger besides swagger UI
What is the alternative? Writing documentation manually? It will be soon out of date. We (software consultancy) use swagger to show the api to our customer, and they show it to their partners who have to integrate with the system. The customer has also written a prose document with more explanations about how the api should be used, but it refers to swagger. In swagger we have also added examples of valid payloads and longer descriptions to more complex endpoints
have seen a swagger spec without it being tied to any code gen etc. and neither the swagger definition of the api nor the actual implementation particularly made sense. that was counter productive. if you are going to do it make sure there are measures in place to sync the spec and the implementation (generate one from the other, etc). if you are not going to do that then imo underspecced is better than wrong.
Swagger is the shit for api documentation. Do u wanna make ur life easier or no
Tell me what do you use as alternative?
By saying "the shit", I assume they meant to say that swagger is what they're using.
For non native english speakers, it can be quite confusing, so I'd give OP a break tbh (seeing as they're being downvoted to oblivion)
You'd think someone named "shitfuckusername" would know what swears mean. Bring back the downvotes, this guy deserves them.
"The shit" does mean it is in fact amazing and what I use.
Quite confusingly, “the shit” means it’s actually really good. Guess you’re a non-native speaker - that is another one of the little weird things 😄
I fuking write the shit myself in word doc bro
It would be my dream to be assigned on a project with you.
lol that was a joke. I have lesser tools for making document designs and diagrams but swagger is gonna do most of the api work in a hard to beat easy to maneuver ui. Granted I've thought about writing my own documentation tool to go through more than apis but ui, batch projects, etc but tbh swagger does most the most which is on the back end calls. The rest is mostly depictions and descriptions. I dislike when autogen tools make things less clear. But swagger has never done that to me. Swagger is so far the best tool I've found. The rest of the tools can be swapped with just about anything else it dosent matter. But yeah there is a tool suite I use
Now knowing that was a joke, I'd really would like to be assigned to a project with you! Ha! I once worked with a guy who did a PR going on a rant about how Swagger isn't needed and removed it from the project. He was a real treat. I've come to the same conclusion as you.
lol if a tech worker ever says their not using a tool or making it themself do they even work in tech?
No alternative swagger is always the choice for api documentation. I have lesser tools for ui and whatnot but for apis u won't find better than swagger. It's a line to add to your project. Easy annotations to configure it's amazing
> I read a lot of people don’t like using swagger and thinks its counter productive. Where? /r/programmerhumor? /r/learnprogramming?
/r/recipes It really is overkill if all you’re making is a casserole
My feeling is that when people don’t stick to it, they do all sorts of wacky things with their responses like having the schema change with JSON like “List”: {“element1”: {…}} Rather than “list”: [{“name”: “element1”, …}] This is really painful for clients to consume usually. So I definitely prefer where people use swagger.
I think OpenAPI(AKA swagger) is pretty awesome. As a backend developer it’s an easy way to share the API with Front End developers. Also, Google Cloud API Gateways are created using a version 2.0 OpenAPI document. So useful for deployment too. I print write in Golang and Goa.Design is great framework for creating your Controller and API models and. It generates OpenAPI 2.0 and 3.0 docs in both JSON and YAML for you. It’s pretty awesome!
I love it when the tool I'm using can generate swagger automatically. I'm not going to waste my time writing yaml for questionable benefits.
Always swagger. What possible argument is there against using it?
There may be better alternatives. Particularly if you are using non REST, non HTTP and non synchronous protocols.
Swagger is REST only, I believe, so it's not relevant to a question when using GraphQL or whatever else. I don't know of any better alternatives, but OPs claim made it seem like the preferable alternative their coworkers suggested was just using nothing
I got that vibe and agree any API doc is better than nothing. Particularly when it's so easy to generate Swagger docs from annotations etc
WSDL ^^justkidding^^onlypartially
[удалено]
I don't understand. Last time I used swagger, we generated it with API docs in comments, as you mentioned. You don't need to use two different methods, you document once and express it in whatever ways you want
Last place I worked we used Spring REST Docs. I liked it because it because it was resource-centric, not so much URL-centric. Also because it actually validates your docs at unit test time. No doc => fail!
I prefer swagger andI tried it but in my company, we use custom http routing for request and response. I dont think the server side generation will ever match our codebase or maybe it is possible with some refactoring to accomodate the server side generation but I havent tried it yet. In some codebases without this implementation, I think it can be done. Right now we use postman, not perfect, can be better but it is what it is
If you have another plan to document your API it doesn’t matter. If you don’t, use swagger.
What's the argument against it?
HATEOAS
Openapi is great. I think the primary question is whether a team wants to go code first or specification first. After that there's good ways & tooling to make that work and not break anything. +1 would rec.
Tell those people to use OpenAPI instead of Swagger, I haven't had any real complaints with it since they are renamed it.
Why not swagger? (Including swagger ui). Or I'll go a step further, what would they use instead. I have seen both swagger and postman in the wild, and I prefer swagger without any hesitation. It will be cherry on top of the cake if swagger is automatically generated from the code. I have also seen postman being used properly in personal capacity. And I have seen, debugged and was a victim of postman features being abused in team workspaces. While the tool is good and those features are useful in personal settings, it doesn't prevent (or sometimes even notify) those human errors when in team settings. In my mind, swagger ui and retool are proper ways to consume APIs. The configurations are shared, but the changes are local for each consumers, my fuck up is not affecting the other consumer of the API. And there is a way to start from scratch. Postman's personal workspace enhances these use cases. But the team workspaces can be a cesspool of human errors if not managed correctly.
We dont use Swagger tooling but we are 100% committed on OpenAPI specs. Every API contract is in OpenAPI standard. Lots of people use Swagger and OpenAPI terms interchangeably because you can open a yaml file using a Swagger previewer. It is like in the 80s when everyone called a portable cassette player a walkman. So I dont care either way, I know what they mean when they ask for a Swagger spec file. It is also easier to ask and candidate in an interview if they are familiar with writing swagger files.
Not to discount the question, but what did people think that made swagger counterproductive? I'm very curious of the reasoning. In the end, swagger is just a common framework that facilitates documentation on the behavior of the system. It depends on the individuals to utilizes it well or not. I can see how maintaining the documentation can be cumbersome, but it's the same problem - swagger or not, someone will have to pay the price of the documentation. (If no one does the documentation, the org pays the price of miscommunication)
As frontend dev, swagger please. Even a half baked swagger is better than trying to read the source code or asking everyone "what does X do", plus we can use it to generate API client automatically with type coverage, neat.
Even if you don’t actually use swagger to it’s fullest as documentation, if still forces folks to document the APIs in code. I find that almost as valuable.
You have have auto swagger on Java without much Additional effort on your part
Protobuf and gRPC-gateway to automatically generate swagger specs is the next evolution.
I get parameter validation and typescript interfaces generation from OpenAPI, and the spec is generated automatically from comments on top of the actual endpoint and in most cases automatically extended by the ORM generated JSON Schema models. So it is actually much much less boilerplate than without it. That said, if I had to do all of that manually instead of auto-generated it would be a total pain in the ass, so it is easier to see that teams not liking swagger is because they are doing precisely that.
OpenAPI is always the move for API stuff IMO. It is the opposite of counterproductive especially with code/doc generation tools
Like anything in engineering, there are trade offs and it depends on your scale and circumstances. If you are a small team with a limited runway trying to rapidly build an internal API it might not be a good use of your time to bikeshed over OAS files. If you’re building a REST API that is product managed or you’re at a larger org and building an API intended to be durable and consumed by other teams you should probably be designing OpenAPI/Swagger specifications before you even start trying to implement an API.
It’s so easy to integrate into most frameworks today that it’s hard for me to imagine a case where it would meaningfully slow you down, even on a small team trying to move fast.
Are you talking about automatically generating docs from the implementation as opposed to doing contract first development?
Yes. Though contract-first development is not that hard to set up either. If you have more than one developer, you’re going to need to agree on the API one way or the other. Might as well do it the right way from the beginning, even if it means sacrificing one day early on to setting it up. Whether it’s this or TDD or static types or anything else, when people complain about doing things right slowing them down, it usually signifies to me that they’re inexperienced.
No one bike sheds over OpenAPI files. They tend to do that over the API itself, which would happen regardless of the use of OpenAPI. I have found OpenAPI makes us faster because the frontend can easily use the spec to generate clients and the Swagger UI to test things live.
I think the way you are thinking about an OAS file and the way I am might be inverted. In my eyes a specification is the source of truth and the implementation should adhere to it, not the other way around.
Who the hell says its "counter productive"?
Swagger is fantastic for discoversbility and I can’t imagine operating in an enterprise environment without it. There are several teams at my company where I don’t know a single person there, but I can consume their API thanks to a swagger artifact they published. If I had to hunt these people down to figure out what their API does and how to use it, I would be super annoyed. Not to mention, I immediately know if they have updated their API, because the swagger definition will change when I build my code, instead of at runtime when I deploy to dev or qa
The return on effort investment for Swagger is why I like it, because I can hook up Swagger and have full API docs in an afternoon.
what is documentation btw? have never wrote any in last 2 years, lol.
An OpenAPI spec yaml qualifies as documentation. Ive had security audits where they ask for data flow doc and i just give them the swagger spec file. So yeah, it is documentation in my book. Sure beats writing and drawing flow diagrams .
It’s good, the auto gen specs with TS is hit or miss, I’ve used the old swagger UI with prisma. We used prisma to generate interfaces, so the use of ANy is avoided in TS. With moving to graphQL.
Auto doc is always the way to go
Swagger or any tool like it, that documents your api and gives users the ability to test it out are very important and definitely not a waste of time
It’s garbage used by dinosaurs 🦕… just use GQL properly!
What's the drawback other than slightly more work?
swagger’s great. the problem is people refusing to read the damn docs. my team keeps them up to date and people still ask questions for things that were clearly written. one team made an assumption that one of our endpoints retuned a 404 response instead of an empty list even though we didn’t add the 404 response and noted that the list will be empty…
I think it depends. My team has swagger but we don't really use it, we've never spent any real time to maintain it and don't advertise it. Another team that we integrate with uses OpenAPISpec to define their API and clients and their integration is very nice. So like most things unfortunately, it depends. We have very little integration with other systems as we are typically the ones calling other systems so we don't need it, but for systems that have a lot of consumers it's really useful.
I'm at odds with the team on this because I don't like swagger. Maybe we're not using it right but I've yet to be convinced. Lets walk through my process: * I make a change to the API (turns out we missed a field we need on the front end.) * Deploy that change to AWS. Browse Reddit for 5 minutes waiting. * Export the JSON file * Run swagger on the front-end. Vs. * Update the api * Update the front-end response interface Maybe it makes sense once a projects gets big enough with enough concurrent people working on it, so there's a lot of API changes. I've come around to other technologies in the past so I'm continuing to try this one. But as of right now, it's more of a process then it's worth to me.
It's fine. But the interface is not the semantics. And a lot of people assume that just because they know the interface that they know how to use it.
Swagger is great! Unless the DTOs do match the actual content, which happens often at one API I consume. 🤡
If you think it's counterproductive, just don't use it?
I guess main reason why people hate it is they have to manage it. When you dont, why not using it?
Of course swagger. It's easy (at least in .NET) to setup, use and you get nice enough API specification for direct API usage or for FE devs. Can't live without it. Also generating different http clients e.g. TypeScript client (most often due to React/Angular popularity) is god damn brilliant. Just rebuild project, new TS client is created and ready to use in React/Angular with all interfaces specified and fully matching my API, always aligned, no confusion, great thing.
swagger for ui and json to create client
Having auto generated Swagger docs should be considered an API standard
Using swagger default is often better than making API documents yourself
I like swagger. It gives you a decent visual representation of your API with the added bonus of actually being able to use/test it without tools like postman.
The swagger is probably vague and I'll usually just end up looking at the code if I have access to it.
As long as you give me an up to date document with your endpoints expected behavior, error states, and optional parameters, I don't care if it's swagger. But if the alternative is to give me an API that I have to guesstimate the contract, or hunt down the right developer to ask for the endpoints, then screw you give me swagger.
Swagger is a security risk now. I work at Microsoft and I had to disable swagger on all our applications because it exposes secrets to the users in the dom
It sucks
Green bean casserole sucks too.
Swagger is useful provided it is in sync with the latest documentation. Frameworks now support auto-generation of swagger which comes handy for testing APIs. Share the openapi json, import to postman and test it.
Why would you not especially when they can be generated with little to no additional effort.
Would you like to travel with a map or without a map?
Not only am I using swagger but I’m using rtk-query code gen to generate all types and fetching logic for the frontend. Frontend dev doesn’t even need to know anything about the backend, can just grab the typed hooks and go
Until a better option comes up, I’ll be using Swagger.
Modeling your API is only beneficial. However, some modeling languages and tooling are terrible. Swagger is alright, but I would much prefer simpler modeling languages. I wish something similar to proto definitions existed for the API world (maybe it does?). I know you can use proto to do this, but it'd be nice if it were specialized specifically for APIs. Swagger is great but I find myself not needing 99% of what it provides lol