feat: Generate Description from Scaladoc

[Javakky-pxv]

Close #498

As discussed in the issue above, it is a bit risky, but at least in our product, Scaladoc documents and OpenAPI documents have the same scope, so we think it is necessary.

[Javakky-pxv]

@kailuowang
Please, review.

[Javakky-pxv]

Need a schema description?

Using runtime-scaladoc-reader, a description can be generated from Scaladoc comments written in the case class.

⚠️ Schema generation from documentation comments is very useful, but should never be used if the scope of scaladoc documentation is different from the scope of OpenAPI documentation.

Add the required dependencies and Compiler Plugin to build.sbt and configure it for use.

embedScaladoc := true
addCompilerPlugin("com.github.takezoe" %% "runtime-scaladoc-reader" % "1.0.3")
libraryDependencies +=  "com.github.takezoe" %% "runtime-scaladoc-reader" % "1.0.3"

For example, a case class might be written as follows.

/**
  * @param name e.g. Sunday, Monday, TuesDay...
  */
case class DayOfWeek(name: String)

The generated JSON will look like this.

{
  "DayOfWeek": {
    "properties": {
      "name": {
        "type": "string",
        "description": "e.g. Sunday, Monday, TuesDay..."
      }
    },
    "required": [
      "name"
    ]
  }
}

[kailuowang]

Just want to understand more about the 2 things

1. Is the runtime-scaladoc-reader library dependency necessary for users?
2. Is the markdown going to be rendered correctly in HTML? (does swagger UI support rendering markdown?

[Javakky-pxv]

@kailuowang
Thanks for your comment!

1. Is the runtime-scaladoc-reader library dependency necessary for users?

Yes, if the user wants to use the Scaladoc embed feature, it is a must. However, if this option is not used, it is not necessary to include it in the dependency.

2. Is the markdown going to be rendered correctly in HTML? (does swagger UI support rendering markdown?

Yes, I have. The Swagger spec says the following about description.
In case you are wondering, I have not actually checked all the specifications, so we have not ruled out the possibility that some MarkDowns may be broken.

Rich Text Formatting

Throughout the specification description fields are noted as supporting CommonMark markdown formatting. Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.

https://swagger.io/specification/

[kailuowang]

Yes, if the user wants to use the Scaladoc embed feature, it is a must.

What puzzles me is that sbt-play-swagger works during compilation time only, Itself is not in the classpath during the play app's runtime. Shouldn't the runtime-scaladoc-reader be needed only for sbt-play-swagger's own runtime (which's in the play app's compilation)?

[Javakky-pxv]

@kailuowang
I am not familiar with the issue, but from the behavior it appears that SwaggerSpecRunner#getClass#getClassLoader is referencing a loaded dependency of the target product.
If so, wouldn't the target project need a runtime-scaladoc-reader?
(Even if it is in the play-swagger dependency, it seems natural that it would not be on ClassLoader or Compiler Plugin unless it is included in the target product's dependencies.)

[Javakky-pxv]

Do you need a deeper investigation into this issue?

[kailuowang]

I think it's worth investigating. Maybe you create a new sbt-test like the existing `generate-docs`, (maybe name it `generate-docs-from-scala-doc`) and play with lib deps settings there and see if you even need the dependency in the target project.

…

On Wed, Sep 7, 2022 at 12:02 PM Kazuma Iemura ***@***.***> wrote: Do you need a deeper investigation into this issue? — Reply to this email directly, view it on GitHub <#499 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAUKOLGODZBEUZH6Q2V6LLV5C4ARANCNFSM6AAAAAAQEVS6NU> . You are receiving this because you were mentioned.Message ID: ***@***.***>

-- Kai

[Javakky-pxv]

@kailuowang
This test is very interesting and I will try it tomorrow.
Be that as it may, as far as I have tried with my product using publishLocal.

• No compiler plugin → @scaladoc is not embedded
• No dependencies only → Error on sbt run.
• Put both → generated correctly.
  I have tried both with sbt run and it works fine.

[Javakky-pxv]

Or is generate-docs-from-scala-doc only needed to verify that it works, and leaving it as a test case is excessive?

[kailuowang]

I see. Sounds like that the lib dependency is needed unless we can tweak the class loader (which might be beneficial anyway see #497). I suggest leaving generate-docs-from-scala-doc as a test case. It can also serve as an example for this feature.

[Javakky-pxv]

@kailuowang
Thank you.
I will address the test cases tomorrow.
I am not familiar enough with sbt's ClassLoader, so I would like to study it and work on this issue as well.

I'm going to bed today. Thank you again.

[Javakky-pxv]

@kailuowang
I created a test folder to try it out.
I hope you will take a look at it.

[kailuowang]

Thanks so much for this meticulous PR!