search

Swagger2Markup / swagger2markup

A Swagger to AsciiDoc or Markdown converter to simplify the generation of an up-to-date RESTful API documentation by combining documentation that’s been hand-written with auto-generated API documentation.
Apache License 2.0
2.5k stars 382 forks source link

Operation title section does not take basePath into account #194

Closed jbrugge closed 7 years ago

jbrugge commented 7 years ago

Swagger2Markup version: 1.1.0

Problem description: If your API is served up at a URL like https://host/v2, then Swagger lets you define that in the Swagger Object as the basePath attribute. In this case, it would be "/v2".

The Swagger spec says that you should then define your Paths Object with a relative path that will be appended to basePath.

The path example (or whatever it is called) that is output following the path title in Swagger2Markup, however, only uses the operation's method and path, and ignores the basePath.

Given the attached sample, the current output in paths.adoc has this:

[[_flubbers_get]]
=== Get all of the flubbers
....
GET /flubbers
....

What I would expect to see is this:

[[_flubbers_get]]
=== Get all of the flubbers
....
GET /v2/flubbers
....

basePath-sample.zip

RobWin commented 7 years ago

Thx. I have a look at it. Btw if you use and like Swagger2markup, we would love to get your GitHub Star.

RobWin commented 7 years ago

Hi, the basePath is currently shown in the overview.adoc file and not placed in front of all other paths. Is that ok for you?

jbrugge commented 7 years ago

Not really, since the paths.adoc shows a short example of each call, and therefore implies that the basePath isn't part of the path that's needed. Also, we aren't using the overview.adoc in our documentation.

RobWin commented 7 years ago

Please try the snapshot version 1.1.1-SNAPSHOT

I've added a new config property swagger2markup.basePathPrefixEnabled. When you set the property to true, the basePath is prepended to all paths.

jbrugge commented 7 years ago

Thanks, that works.

pachecolp commented 7 years ago

Hi, RobWin!

I need this feature too, but I can't make it work.

I'm using the swagger2markup-maven-project-template as basis (just pulled it) and added the following line to the <properties> section of the pom.xml.

<swagger2markup.basePathPrefixEnabled>true</swagger2markup.basePathPrefixEnabled>

With that, the documentation still build, but I didn't get the basePath prepended to the path.

I guessed I needed to update the version of the swagger2markup-maven-plugin, so I changed the value of <swagger2markup.plugin.version>.

<swagger2markup.plugin.version>1.1.1</swagger2markup.plugin.version>

Now I get an error at the end of the build:

[ERROR] Failed to execute goal io.github.swagger2markup:swagger2markup-maven-plugin:1.1.0:convertSwagger2markup (default) on project swagger2markup-maven-project-template: Failed to execute goal 'convertSwagger2markup': Tags must not be empty, when operations are grouped by tags -> [Help 1]

Running in debug mode I get:

[ERROR] Failed to execute goal io.github.swagger2markup:swagger2markup-maven-plugin:1.1.0:convertSwagger2markup (default) on project swagger2markup-maven-project-template: Failed to execute goal 'convertSwagger2markup': Tags must not be empty, when operations are grouped by tags -> [Help 1]
org.apache.maven.lifecycle.LifecycleExecutionException: Failed to execute goal io.github.swagger2markup:swagger2markup-maven-plugin:1.1.0:convertSwagger2markup (default) on project swagger2markup-maven-project-template: Failed to execute goal 'convertSwagger2markup'
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:212)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:153)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:145)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:116)
    at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:80)
    at org.apache.maven.lifecycle.internal.builder.singlethreaded.SingleThreadedBuilder.build(SingleThreadedBuilder.java:51)
    at org.apache.maven.lifecycle.internal.LifecycleStarter.execute(LifecycleStarter.java:128)
    at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:307)
    at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:193)
    at org.apache.maven.DefaultMaven.execute(DefaultMaven.java:106)
    at org.apache.maven.cli.MavenCli.execute(MavenCli.java:862)
    at org.apache.maven.cli.MavenCli.doMain(MavenCli.java:286)
    at org.apache.maven.cli.MavenCli.main(MavenCli.java:197)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:498)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced(Launcher.java:289)
    at org.codehaus.plexus.classworlds.launcher.Launcher.launch(Launcher.java:229)
    at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode(Launcher.java:415)
    at org.codehaus.plexus.classworlds.launcher.Launcher.main(Launcher.java:356)
Caused by: org.apache.maven.plugin.MojoFailureException: Failed to execute goal 'convertSwagger2markup'
    at io.github.swagger2markup.Swagger2MarkupMojo.execute(Swagger2MarkupMojo.java:74)
    at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:134)
    at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:208)
    ... 20 more
Caused by: java.lang.NullPointerException: Tags must not be empty, when operations are grouped by tags
    at org.apache.commons.lang3.Validate.notEmpty(Validate.java:297)
    at io.github.swagger2markup.internal.document.PathsDocument.buildsPathsSection(PathsDocument.java:131)
    at io.github.swagger2markup.internal.document.PathsDocument.apply(PathsDocument.java:113)
    at io.github.swagger2markup.Swagger2MarkupConverter.applyPathsDocument(Swagger2MarkupConverter.java:199)
    at io.github.swagger2markup.Swagger2MarkupConverter.toFolder(Swagger2MarkupConverter.java:184)
    at io.github.swagger2markup.Swagger2MarkupMojo.execute(Swagger2MarkupMojo.java:69)
    ... 22 more

What else should I change in the template project to make it work?

(BTW, you already have my start. :-) )

RobWin commented 7 years ago

Hi @grootknol The swagger2markup-maven-plugin v1.1.1 has not been released yet, but you can still use swagger2markup-maven-plugin v1.1.0 and use Swagger2Markup v1.1.1 by changing:

<swagger2markup.version>1.1.0</swagger2markup.version> to

<swagger2markup.version>1.1.1</swagger2markup.version>

Does it work for you?

RobWin commented 7 years ago

Fixed in v1.1.1

pachecolp commented 7 years ago

Nope. I still get the same error:

[ERROR] Failed to execute goal io.github.swagger2markup:swagger2markup-maven-plugin:1.1.0:convertSwagger2markup (default) on project swagger2markup-maven-project-template: Failed to execute goal 'convertSwagger2markup': Tags must not be empty, when operations are grouped by tags -> [Help 1]

Should I open a new issue?

RobWin commented 7 years ago

Sry, I misread your exception. You got Tags must not be empty, when operations are grouped by tags, which means: If you want to group your operations by tags, you have to specify a list of global tags and assign a tag to each operation. If you don't want to group by tags, then please remove <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>

pachecolp commented 7 years ago

I had tags in the operations but I hadn't a tags section at the root. The Swagger Editor didn't complain about that.

Adding the root tags section fixed the build problem, but the basePath wasn't prepended to the paths neither with or without the <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>.

Here is the asciidoc generated:

=== URI scheme
[%hardbreaks]
__Host__ : api.bla.com.br
__BasePath__ : /v1/leve
__Schemes__ : HTTP, HTTPS

=== Tags

* orçamento
* proposta
[[_paths]]
== Paths

[[_criarorcamento]]
=== Cria um orçamento Bla
....
POST /orcamento
....
RobWin commented 7 years ago

Could you please show me your pom.xml?

pachecolp commented 7 years ago

Sure.

pom.zip

RobWin commented 7 years ago

Hi,

you've added the property <swagger2markup.basePathPrefixEnabled>true</swagger2markup.basePathPrefixEnabled> to the wrong section (global properties). You have to add the property to the configuration section of the plugin. 


<configuration>
    <swaggerInput>${swagger.input}</swaggerInput>
    <outputDir>${generated.asciidoc.directory}</outputDir>
    <config>
        <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
        <!-- <swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy> -->
        <swagger2markup.extensions.dynamicOverview.contentPath>${project.basedir}/src/docs/asciidoc/extensions/overview</swagger2markup.extensions.dynamicOverview.contentPath>
        <swagger2markup.extensions.dynamicDefinitions.contentPath>${project.basedir}/src/docs/asciidoc/extensions/definitions</swagger2markup.extensions.dynamicDefinitions.contentPath>
        <swagger2markup.extensions.dynamicPaths.contentPath>${project.basedir}/src/docs/asciidoc/extensions/paths</swagger2markup.extensions.dynamicPaths.contentPath>
        <swagger2markup.extensions.dynamicSecurity.contentPath>${project.basedir}src/docs/asciidoc/extensions/security</swagger2markup.extensions.dynamicSecurity.contentPath>
        <swagger2markup.basePathPrefixEnabled>true</swagger2markup.basePathPrefixEnabled>
    </config>
</configuration>
pachecolp commented 7 years ago

Great! That was exactly it! Sorry for the dumb mistake and thanks a lot for your time! Best regards!