I have a problem....
I need to document my REST style Web Service, and I think there are 3
types of documentation I need
1) JavaDocs -> targeted at developers working w/ my Java code
2) Users of my Web Service -> target at humans who need to understand my API
typically this documentation is in the form of HTML pages
that I need to create (and maintain)
for example:
https://documents.worldbank.org/en/publication/documents-reports/api
https://openweathermap.org/api
https://open-meteo.com/en/docs
I have create a Java tool to read your Endpoints and generate a HTML page
to use my RESTDocumentation tool, I do these steps:
0) import the project into Eclipse (RESTDocumentationBuilder.zip)
1) the build requires my Endpoint code to be compiled
so I right click my project and run Maven Build w/ the compile goal
2) the build requires a help folder to put the HTML page into so I
create src/main/webapp/help
3) the build project has a Windows batch file to generate the HTML
page, I need to set my project name in there, then run the
Windows batch file
4) optional: I can create an index.html (in src/main/webapp) to
point to my new help page, for example:
World REST Web Service
World REST Web Service
See: api for the details of the API.
3) I need to create machine readable documentation for Client code to parse
this documentation will not be HTML, but should be...
JSON
YAML
XML
???
there are a number of standards for documenting REST style Web Services
Swagger
OpenApi (grew out of Swagger)
RAML
WADL
and more
I will use OpenApi, because I am lazy, and will have it generated for me
to auto-generate OpenApi documentation I need to add entries to my pom.xml file
and that is it...
I need to add:
2.2.22
io.swagger.core.v3
swagger-jaxrs2
${swagger-version}
io.swagger.core.v3
swagger-jaxrs2-servlet-initializer-v2
${swagger-version}
after I update the pom.xml (and clean JBoss)
I run the appl on the server and go to this (generated URL)
http://localhost:8080/ToDoRESTWebService/api/openapi.json