springfox / springfox-javadoc Goto Github PK

The Swagger 2.0 spec supports two fields on @ApiOperation: "summary" and "notes". In the current implementation, we set only the "notes" using the entire value of the comment.

However, the Javadoc spec also supports a summary and a description. From the Javadoc tech notes:

First Sentence
The first sentence of each documentation comment should be a summary sentence that contains a concise but complete description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first block tag. The javadoc command copies this first sentence to the member summary at the top of the HTML page.

Using this spec, we can provide both "summary" and "notes" for @ApiOperation. It can also be used on class docs to specify @Api "tags".

@dilipkrish, do you think this is a good approach? I can help with implementing this if you don't foresee any issues.

I see that last master update was 2 years ago, nine PRs are waiting for merge, 6 of which are from GitHub.

This feature is really cool thing that can save a lot of time and prevent repeating API descriptions.

@dilipkrish, are you with us? Can you approve PRs? Or this repo is no longer needed due to alternative solutions?

So... like the README said, I added the plugin snippet to the pom.xml.
I added it in

<project 
    ...
    <build>
        <plugins>
            >>> HERE <<<

Is that right?

I also got the following warning:

Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-javadoc-plugin:2.10.4:javadoc 

(execution: default, phase: process-classes)

By simply running the project (using spring boot), I still see no javadoc being used in swagger descriptions. I guess I'm missing a step but I'm a bit in the dark here. Could anyone please point me in the right direction?

Hello guys,

Can I use this plugin with Gradle? If yes then how?

Thanks!

Also make the build portable and not depend on build environment as much, especially the tests

I would like to update the project to make it compatible with Java9+ and the new Doclet API.

In the same time I would like to make it compatible with Gralde build.

In order to follow the the work started in another pull request I have also migrated to springfox-swagger2-3.0.0-SNAPSHOT

If there is a request mapping as below:
@RequestMapping(value={"/path1", "path2"})
Then in the generaeted properties file entries of this is found as below:
/{"/path1",\ "/path2"}.POST.param.operationType=
As a result the swagger api can't find the request mapping in the properties file as it searches for entries like:
/path1.POST.param.operationType.
The fix should be to generate multiple entries in the properties file like:
/path1.POST.param.operationType /path2.POST.param.operationType
for each of the values of maultivalued request mapping.

Hi. Could you answer please, when should we expect the release of the plug-in in the repository? Thanks for your answer.

Currently only service and the operations can be documented using Javadoc. It would be nice if the model could be also documented using Javadoc.

Can official provide a simple demo

Dokka is the Javadoc equivalent for Kotlin. It provides hooks to run custom plugins similar to doclets.

Dokka can parse both KDoc and Javadoc, so it would be great to support this for Spring MVC projects written using Kotlin/Java.