Skip to content

asciidoc markup generator - #3845

Merged
wing328 merged 16 commits into
OpenAPITools:masterfrom
man-at-home:asciidoc-generator--pr
Sep 14, 2019
Merged

asciidoc markup generator#3845
wing328 merged 16 commits into
OpenAPITools:masterfrom
man-at-home:asciidoc-generator--pr

Conversation

@man-at-home

@man-at-homeman-at-home commented Sep 5, 2019•
edited
Loading

Copy link
Copy Markdown
Contributor

PR checklist

  • [x ] Read the contribution guidelines.
  • [ x] Ran the shell script under ./bin/ to update Petstore sample so that CIs can verify the change. (For instance, only need to run ./bin/{LANG}-petstore.sh, ./bin/openapi3/{LANG}-petstore.sh if updating the {LANG} (e.g. php, ruby, python, etc) code generator or {LANG} client's mustache templates). Windows batch files can be found in .\bin\windows\. If contributing template-only or documentation-only changes which will change sample output, be sure to build the project first.
  • [ x] Filed the PR against the correct branch: master, 4.1.x, 5.0.x. Default: master.
  • Copied the technical committee to review the pull request if your PR is targeting a particular programming language.

Description of the PR

  • added a basic asciidoc markup documentation generator (oriented on html or cwiki)

two advantages:

  • a) printable output for openapi specs (pdf, more options via docbook)
  • b) generator allows to augment (include or link) the generated documentation with other outputs via mustache filters
  • augmenting info would be: sample output by spring restdoc, hand written spec prose and in this case wiremock sample data generated by spring boot cloud contract

technical commitee: (core team as asciidoc markup has no team)

@wing328@jimschubert@cbornet@ackintosh@jmini@etherealjoy

@man-at-home
basic asciidoc markup generation
def2301
@man-at-home
asciidoc markup include processing with mustache filter
15e8ceb
@man-at-home
asciidoc tests, separate include filters
12f2e92
@man-at-home
asciidoc petstore sample
d938eca
@man-at-home
add asciidoc generator to readme
438ed43
@man-at-home
test asciidoc generator for all include files with own json spec.
f032332
@man-at-home
link fillter to link generated test data into asciidoc markup
e9bda85
@man-at-home
fix and cleanup names asciidoc tests.
6cb7ee9
@man-at-home
Merge branch 'master' into asciidoc-generator--pr
01a4c4d
* master:
Add missing files to the form request (#3834)
fix warnings in csharp-netcore client (#3831)
Bug #2845 typescript angular inheritance (#3812)
Add nickmeinhold to Dart technical committee (#3830)
Revert "1792 fix remote spec handling and hash calculation (#3440)"
fixed bug where nullApi.java would be generated. Instead, generated DefaultApi.java to match the default path /{pathParam} (#3821)
1792 fix remote spec handling and hash calculation (#3440)
Add gRPC Protobuf schema generator (#3818)
Better Go code format (#3819)
@man-at-home
fix travis build error, removed windows line endings from mustache as…
24046cf
…ciiidoc templates.
@man-at-home
asciidoc generator: comment and reduce visibility of helper method (f…
12086f7
…ix dron build)
@man-at-home
asciidoc: windows linefeed again (fix travis ci)
9bf9b7f
@man-at-home
asciidoc generator: remove \t and format again.
9697f9e
@man-at-home

man-at-home commented Sep 5, 2019

Copy link
Copy Markdown
ContributorAuthor

need to fix several ci builds it seems (mostly style or windows specific stuff like \r) the next days..

@man-at-home
fix ascidoc generator ci builds ... ongoing..
cb3e9db
@man-at-home
asciidoc: add generator .md files, unix line ending.
138b88c
@man-at-home
Merge branch 'master' into asciidoc-generator--pr
34eea3a
* master:
Following up for #3440 (1792 fix remote spec handling and hash calculation) (#3826)
[client][go] avoid duplicated reflect imports (#3847)
wing328
wing328 reviewed Sep 14, 2019
View reviewed changes
Comment thread...generator/src/main/java/org/openapitools/codegen/languages/AsciidocDocumentationCodegen.java
@@ -0,0 +1,260 @@
package org.openapitools.codegen.languages;

@wing328wing328Sep 14, 2019

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll add the copyright header in a separate PR.

wing328
wing328 approved these changes Sep 14, 2019
View reviewed changes

@wing328wing328 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested locally and looks pretty good :+1

wing328
wing328 reviewed Sep 14, 2019
View reviewed changes
Comment threadsamples/documentation/asciidoc/index.adoc
=== Pet


[.addPet]

@wing328wing328Sep 14, 2019

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@man-at-home we may need to prefix it with the class name (e.g. Pet_addPet) as multiple classes can have the same method (e.g. both Pet and User have the same method getId: Pet_getId, User_getId).

@man-at-homeman-at-homeSep 14, 2019

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will look into it. At the moment the generated doc does not use these tags, but the idee would be to allow links to specific calls (if the generated docs format is linkable like html)

@wing328wing328 added this to the 4.1.3 milestone Sep 14, 2019
@wing328
wing328 merged commit 8055231 into OpenAPITools:masterSep 14, 2019
@wing328

wing328 commented Sep 14, 2019

Copy link
Copy Markdown
Member

FYI. I've added you as the template creator of asciidoc in 8f43373

@man-at-home

man-at-home commented Sep 14, 2019

Copy link
Copy Markdown
ContributorAuthor

thanks a lot.

@wing328

wing328 commented Sep 17, 2019

Copy link
Copy Markdown
Member

@man-at-home do you have a Twitter account? We will tag you in a tweet to promote the new generator.

@man-at-home

man-at-home commented Sep 18, 2019

Copy link
Copy Markdown
ContributorAuthor

no twitter handle in use, sorry

@wing328

wing328 commented Sep 20, 2019

Copy link
Copy Markdown
Member

That's ok. I've sent out the following:

https://twitter.com/oas_generator/status/1174992564576911360

https://news.ycombinator.com/item?id=21025034

https://www.reddit.com/r/opensource/comments/d6stws/generate_api_documentation_in_asciidoc_format/

Have a nice weekend!

@wing328

wing328 commented Oct 4, 2019

Copy link
Copy Markdown
Member

@man-at-home thanks for the PR, which has been included in the v4.1.3 release: https://twitter.com/oas_generator/status/1180123829626003456

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@wing328wing328wing328 approved these changes

Assignees

No one assigned

Labels

Doc: AsciiDocEnhancement: New generator

Projects

None yet

Milestone

4.1.3

Development

Successfully merging this pull request may close these issues.

2 participants

@man-at-home@wing328