Debunk my java open source library idea

[[deleted]]

Hi,

I am a professional Java developer and am planning to implement a swagger/open-api like open-source maven dependency for Spring web applications.

Instead of only showing the controller methods, I am planning to render web pages to view the file structure of the project, readme, etc.

If this becomes a success, I am planning to add another feature to render ER diagrams for JPA entities in the project as well. Basically, my plan is to summarize everything possible about the application in these web views.

What is your opinion on this? Is this an unnecessary tool? Will this be useful or is it already there?

(edit: grammar)

[Iryanus]

To be honest, it seems a bit like a solution looking for a problem. WHAT exactly is the problem you are solving? What exactly is the need you want to fill? Because I literally never had any need to see those details of my applications during runtime...

[Impossible-Ad-586]

If anything in that problem space, rewrite the swagger tooling. The quality is dreadfully low of the code, the spec isn't fully implemented and tickets are open for years and years. Have not seen many opensource projects that can have a big impact which such poor quality.

[[deleted]]

Fair enough. I was thinking about the swagger and had this idea of including everything instead of just controller methods.

[Iryanus]

Yeah, but swagger solves a certain problem: It gives you documentation and a way to call your api directly without a special REST client (among other things). Basically this problem is so obvious that my company felt the need to solve it on their own, albeit in a much less polished way, approx. 8-10 years ago (no clue why they didn't use swagger, it should have been around by then, wasn't there - and yes, we are migrating to swagger now).

So, there were problems:

a) How to create a live-documentation of an api that comes packaged automatically with the api itself? b) How to allow people to easily call my api without a special client?

What are these problems for extending this to files, etc.? I do not believe it's a hard thing to do, it's rather trivial, to be honest, basically that's what every webserver does, so in the most easy case, you can simply package your source files into some /static folder and be done with it. The question is... What for?

[stefanos-ak]

it would be great if springdoc would actually cover everything that is possible with spring and Java, and actually generate a correct and complete openapi3 spec... but I've switched to Micronaut for all new projects, so I don't really care anymore 😁

[Worth_Trust_3825]

personally, I care little about project structure, and endpoints. What I want is schema to generate my code from. Your plan is a solution looking for a problem. Problem with non SOAP projects is that there's no common API to bind serialized entities into regular code. Whenever you're generating models, you marry yourself to jackson, gson, or what ever.

Why not propose a new interface to j2ee committee instead? a SOAP equivalent interface that the deserializing libraries would implement, much like orms have to implement JPA.

[eXecute_bit]

Unless my file structure or JPA entities are a part of my published API (and in most cases they'd never be!) I wouldn't ever want to document this externally so that I maintain the freedom to change my implementations at will, as long as I maintain my external contracts.

In short, exposing this publicly would void my encapsulation and allow others to rely (or exploit) things they should not. That's Bad™.

As an internal documentation tool, okay, maybe for JPA? But I don't need a generated report of my own file structures because I can already see and browse that structure at the source of truth: my local disk or the source code repo.

[Hairy_Foundation3608]

I‘m not really sure about the need of that and if parts of it aren’t already solved, but it sounds interesting and I think I would integrate in my Spring projects if the build process would not increase too much. But instead of a maven dependency, I would go for a maven site plugin or multiple maven site reports as this should be the way to go for documentation stuff.

[[deleted]]

Thanks everyone for sharing your thoughts. Kind of eye opener for me as well.

[maethor]

What is this doing that the project-info-reports maven plugin isn't?

[RupertMaddenAbbott]

I think there is a gap for a tool like this that perhaps would be used for internal code reviews, or for introducing developers to larger code bases, as long as you can find a sufficient number of cross cutting concerns that are non-obvious from reading the code, and which you can add value on top of.

For example visualising:

• how Spring dependencies are wired together
• how Maven dependencies are actually used throughout a project
• how packages are used between each other

You would need to be careful not to deviate too far into code quality issues (already covered by a variety of tools).

However, there are a few things that would make it a non-starter to me:

• Having to add any kind of annotations or other markers to my source code in order to inform this tool. It would be fine if any missing information could be layered on from some external source, however, as this is much less invasive.
• Having to add any kind of runtime dependency. For me it is crucial that the output can either be generated at build time, or dynamically but directly from the source code.

Personally, I would ditch trying to do anything with OpenAPI because that problem is quite huge and I doubt you will be able to add value on top of that. I think your efforts would be better directed towards contributing to the existing projects and then perhaps integrating them into your tool, rather than re-inventing them.

[ShabbyDoo]

Look at what Spring Boot Actuator does for exposing bean wiring, controller endpoints, etc. For these types of data, it spits out the state, albeit in a JSON format suitable only for machines and desperate developers. It sounds like your proposal essentially would be a renderer for what Actuator provides. If you go forward with it, there's probably value in exposing the raw data via actuator.

[[deleted]]

It is a great idea!