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.

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

Feature markdown description #377

Merged
merged 63 commits into from
Jun 17, 2019

Conversation

Nerzal
Copy link
Contributor

@Nerzal Nerzal commented Apr 16, 2019

Describe the PR
Added new annotation "@description.markdown" which parses the general api description from a api.md file in the given directory
Added new annotation "@tag.description.markdown" which parses the tag description from a tagname.md file in the given directory
Added a new parameter for the cli which takes the markdown directory path
Added 2 test methods for the stuff above
Fixed some linter warnings.

Additional context
This addition is mainly for the use with redoc, as redoc is able to render markdown, which allows us to create stunning documentations using code annotations in combinition with markdown files stored in the project. <3

Link to redoc: https://github.com/Rebilly/ReDoc

@Nerzal
Copy link
Contributor Author

Nerzal commented May 12, 2019

@easonlin404 beside the broken CI Build.
Do you find that feature useful?
If so, i can fix the issues with CI etc.

@codecov-io
Copy link

codecov-io commented May 12, 2019

Codecov Report

Merging #377 into master will decrease coverage by 1.05%.
The diff coverage is 55.31%.

Impacted file tree graph

@@            Coverage Diff             @@
##           master     #377      +/-   ##
==========================================
- Coverage   84.71%   83.65%   -1.06%     
==========================================
  Files           7        7              
  Lines        1341     1383      +42     
==========================================
+ Hits         1136     1157      +21     
- Misses        119      130      +11     
- Partials       86       96      +10
Impacted Files Coverage Δ
gen/gen.go 60.78% <40%> (-8.11%) ⬇️
parser.go 82.33% <59.45%> (-1.11%) ⬇️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b534de4...2d4747a. Read the comment docs.

@Nerzal
Copy link
Contributor Author

Nerzal commented May 12, 2019

Here is an example, of a markdown tag description i created using the features in this pr
grafik

@easonlin404
Copy link
Member

@Nerzal Thanks for your contributions. 👍 IMO, it's a useful feature to support markdown descriptions.
Would you please add example/at readme to demonstrate how to use? And this PR we needs more time to review it since having change a lot.

README.md Outdated Show resolved Hide resolved
coverage/sorter.js Outdated Show resolved Hide resolved
parser.go Outdated Show resolved Hide resolved
parser_test.go Outdated Show resolved Hide resolved
parser_test.go Outdated Show resolved Hide resolved
parser_test.go Outdated Show resolved Hide resolved
parser_test.go Outdated Show resolved Hide resolved
property_test.go Outdated Show resolved Hide resolved
property_test.go Outdated Show resolved Hide resolved
Copy link
Member

@easonlin404 easonlin404 left a comment

Choose a reason for hiding this comment

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

leave comment, thx.

@easonlin404 easonlin404 added this to the v1.6.0 milestone May 14, 2019
@pei0804
Copy link
Member

pei0804 commented May 14, 2019

I secure time to see.

@Nerzal
Copy link
Contributor Author

Nerzal commented May 14, 2019

I'll try to add to add examples + cleanup the branch in the next days. Currently only have little time caused by workload :D

Nerzal and others added 21 commits June 12, 2019 13:51
* refactor: return error instead of panic

* fix fmt check

* fix error check

* refine getPropertyName

* refine CheckSchemaType method
* refactor: return error instead of panic

* fix fmt check

* fix error check

* refine getPropertyName

* refine CheckSchemaType method
@Nerzal
Copy link
Contributor Author

Nerzal commented Jun 12, 2019

I merged master branch again, cause of merge conflicts.

@easonlin404 easonlin404 merged commit 6170d1b into swaggo:master Jun 17, 2019
@josephzidell
Copy link
Contributor

@Nerzal Just stumbled across this beautiful PR. How can you use redoc with swaggo?

@Nerzal
Copy link
Contributor Author

Nerzal commented Jun 21, 2019

Heyho, i'll add another pr soon, which introduces this feature.

In the meantime you can jut add this and add deliver the HTML content of the constant as response.

package docs

// RedocDocumentation is a static HTML used to deliver the redoc API-Documentation
const RedocDocumentation = `

<title>Your Title</title>
<!--
ReDoc doesn't change outer page styles
-->
<style>
  body {
    margin: 0;
    padding: 0;
  }
</style>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script> `

See #396 as reference issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants