Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Implement automatic generation of Open API / Swagger documentation from JavaDoc comments in controllers #1040

Closed
ipolevoy opened this issue Aug 7, 2020 · 10 comments
Assignees

Comments

@ipolevoy
Copy link
Member

ipolevoy commented Aug 7, 2020

the idea is to develop the OpenAPI documentation directly in the controller Java files as JavaDoc, but then generate the OpenAPI - compatible format to expose as real documentation. This way, the JavaDoc will also serve and an official API documentation.

Also, it makes sense to carve out blocks of JavaDoc for this, such that if any content is outside such a block, it will not be part of the exposed API - this is necessary for internal comments, implementational detail, etc.

@ipolevoy
Copy link
Member Author

ipolevoy commented Aug 7, 2020

@ipolevoy ipolevoy self-assigned this Oct 28, 2020
@ipolevoy
Copy link
Member Author

this is somewhat related: https://github.com/OpenAPITools/openapi-generator - generates server stubs based on OpenAPI spec.

However, the first support is to generate API docs from comments in code

@ipolevoy
Copy link
Member Author

also, see this: javaparser/javaparser#325

@ipolevoy
Copy link
Member Author

Here is another good resource: https://github.com/readmeio/swagger-inline

@ipolevoy
Copy link
Member Author

It makes sense to make it possible to:

  1. generate json definitions at build time
  2. Generate definitions at run time using a special controller

@ipolevoy
Copy link
Member Author

For the option 2, need to compile with javadoc though

@ipolevoy
Copy link
Member Author

Maybe generate defs at run time and serve that live?

@ipolevoy
Copy link
Member Author

ipolevoy commented Feb 8, 2021

Once this is implemented, comment here: https://stackoverflow.com/questions/55805156/swagger-support-for-javalite-project

ipolevoy added a commit that referenced this issue May 10, 2021
…ation from JavaDoc comments in controllers - implemented a search and printing of a routes table for standard routes from classs files. Next: refactoring, and print of the routes table from sources.
ipolevoy added a commit that referenced this issue May 10, 2021
…ation from JavaDoc comments in controllers - implemented a search and printing of a routes table for standard routes from classs files. Next: refactoring, and print of the routes table from sources.
ipolevoy added a commit that referenced this issue May 14, 2021
…ation from JavaDoc comments in controllers - properly finds and prints routes from classpath. Next step is to enhance with data from source code.
ipolevoy added a commit that referenced this issue May 24, 2021
…ation from JavaDoc comments in controllers - Custom route generation is partially complete
ipolevoy added a commit that referenced this issue Jun 1, 2021
…ation from JavaDoc comments in controllers - Completed custom route generation, removed source parsing, improved tests. Next: Actual generation of OpenAPI JSON and YAML for a test project.
ipolevoy added a commit that referenced this issue Jun 2, 2021
…ation from JavaDoc comments in controllers - improved messaging, prints, hardened tests. What is left: generate the actual OpenAPI docs
ipolevoy added a commit that referenced this issue Jun 4, 2021
…ation from JavaDoc comments in controllers - Implemented generation of the OpenAPI docs from endpoints. What is left:

* Integrate with Maven Mojo
* Implement an integration test
ipolevoy added a commit that referenced this issue Jun 4, 2021
#1040 - Implement automatic generation of Open API / Swagger documentation from JavaDoc comments in controllers - still work in progress, but time to sync
ipolevoy added a commit that referenced this issue Jun 14, 2021
…ation from JavaDoc comments in controllers - Implemented reading OpenAPI docs from corresponding files

Next:
1. Implement a tag structure: "table": "<@table blah.html/@>" Freemarker?
2. Validate JSON format junk by  chunk
3. Format output
ipolevoy added a commit that referenced this issue Jun 15, 2021
…ation from JavaDoc comments in controllers - Implement a tag structure: "table": "<@table blah.html/@>" Freemarker.

Next:
1. Validate JSON format junk by  chunk
2. Format output as JSON with a flag (pretty/compressed)
ipolevoy added a commit that referenced this issue Jun 17, 2021
…ation from JavaDoc comments in controllers - Implemented validation of JSON junks, format output as JSON, completed, GenerateMojo and HelpMojo

Next:
Implement a @description annotation on endpoints to be printed by the "routes" goal
@ipolevoy
Copy link
Member Author

code done, need to add documentation

ipolevoy added a commit that referenced this issue Jun 17, 2021
…ation from JavaDoc comments in controllers - renamed plugin to: aw-mate.
ipolevoy added a commit that referenced this issue Jul 13, 2021
…ation from JavaDoc comments in controllers - added a dependency exclusion
ipolevoy added a commit that referenced this issue Feb 1, 2022
…ation from JavaDoc comments in controllers - Implementation completed. Next: develop an example application that replicates PetShop API and generates corresponding documentation
ipolevoy added a commit that referenced this issue Feb 3, 2022
…ation from JavaDoc comments in controllers - fixed a bug where multiple configurations for the same endpoint but different HTTP methods would overwrite each other.
ipolevoy added a commit that referenced this issue Feb 3, 2022
…ation from JavaDoc comments in controllers - added test checks
ipolevoy added a commit that referenced this issue Feb 3, 2022
…ation from JavaDoc comments in controllers - fixed a broken test
@ipolevoy
Copy link
Member Author

ipolevoy commented Feb 3, 2022

What is left:

  1. The Open API generates documentation for every route, whether it has OpenAPI documentation or not. This means that the output file will have entries for endpoints that do not even have the documentation. Let's hide endpoints from the Open API if such endpoints do not have OpenAPI documentation, whether in a file or in an annotation format.
  2. Complete the example app with file and annotation examples.
  3. Add documentation to the site.

ipolevoy added a commit that referenced this issue Feb 10, 2022
…ation from JavaDoc comments in controllers - fixed numerous bugs, improved tests. Test coverage in EndpointFinder is 90%.
ipolevoy added a commit that referenced this issue Feb 11, 2022
…ation from JavaDoc comments in controllers - removing dead wood
ipolevoy added a commit that referenced this issue Feb 11, 2022
…ation from JavaDoc comments in controllers - fixed a print mojo
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant