Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

asciidoc markup generator #3845

Merged
merged 16 commits into from
Sep 14, 2019
Merged

asciidoc markup generator #3845

merged 16 commits into from
Sep 14, 2019

Conversation

man-at-home
Copy link
Contributor

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

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
Copy link
Contributor Author

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
...generator/src/main/java/org/openapitools/codegen/languages/AsciidocDocumentationCodegen.java
@@ -0,0 +1,260 @@
package org.openapitools.codegen.languages;
Copy link
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
Copy link
Member

@wing328 wing328 left a comment

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
samples/documentation/asciidoc/index.adoc
=== Pet


[.addPet]
Copy link
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).

Copy link
Contributor Author

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)

@wing328 wing328 added this to the 4.1.3 milestone Sep 14, 2019
@wing328 wing328 merged commit 8055231 into OpenAPITools:master Sep 14, 2019
@wing328
Copy link
Member

wing328 commented Sep 14, 2019

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

@man-at-home
Copy link
Contributor Author

thanks a lot.

@wing328
Copy link
Member

wing328 commented Sep 17, 2019

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

@man-at-home
Copy link
Contributor Author

no twitter handle in use, sorry

@wing328
Copy link
Member

wing328 commented Sep 20, 2019

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
Copy link
Member

wing328 commented Oct 4, 2019

@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 free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@wing328 wing328 wing328 approved these changes

Assignees
No one assigned
Labels
Doc: AsciiDoc Enhancement: 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