diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..53bad22 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,44 @@ +language: csharp +dotnet: 3.1 +mono: none +solution: Swagger.Documentation.sln +branches: + only: + - main +before_script: + - dotnet restore +script: + - dotnet build + - dotnet test ./test/Swagger.Documentation.Test -c $CONFIGURATION -f netcoreapp3.1 +after_success: + - dotnet minicover instrument + - dotnet minicover reset + - dotnet test --no-build ./test/Swagger.Documentation.Test -c $CONFIGURATION -f netcoreapp3.1 + - dotnet minicover uninstrument + - dotnet minicover report + - dotnet minicover coverallsreport --output "coveralls.json" --service-name "travis-ci" --service-job-id $TRAVIS_JOB_ID +before_deploy: + - git checkout origin/main && git fetch && git remote set-url origin https://${GITHUB_OAUTH_TOKEN}@github.com/ZEXSM/Swagger.Documentation.git + - PR_TITLE=$(git log -1 --pretty='%f') + - LAST_TAG=$(echo $(git describe --tags $(git rev-list --tags --max-count=1)) | cut -d'v' -f 2) + - CURRENT_MAJOR=$(echo $LAST_TAG | cut -d. -f 1) + - CURRENT_MINOR=$(echo $LAST_TAG | cut -d. -f 2) + - CURRENT_PATCH=$(echo $(echo $LAST_TAG | cut -d. -f 3) | cut -d- -f 1) + - RC=$(echo $(echo $LAST_TAG | cut -d. -f 3) | cut -d- -f 2) + - MAJOR=$(([ "$RC" == "rc" ] && echo $CURRENT_MAJOR) || ([ "$(echo $PR_TITLE | grep -oP 'release')" == "release" ] && echo $(($CURRENT_MAJOR+1))) || echo $CURRENT_MAJOR) + - MINOR=$(([ "$RC" == "rc" ] && echo $CURRENT_MINOR) || ([ "$(echo $PR_TITLE | grep -oP 'release')" == "release" ] && echo 0) || ([ "$(echo $PR_TITLE | grep -oP 'feature')" == "feature" ] && echo $(($CURRENT_MINOR+1))) || echo $CURRENT_MINOR) + - PATCH=$(([ "$RC" == "rc" ] && echo $CURRENT_PATCH) || ([ "$(echo $PR_TITLE | grep -oP 'release')" == "release" ] && echo 0) || ([ "$(echo $PR_TITLE | grep -oP 'feature')" == "feature" ] && echo 0) || echo $(($CURRENT_PATCH+1))) + - NEW_TAG=$(echo $MAJOR.$MINOR.$PATCH) + - PACKAGE_VERSION=${NEW_TAG:-$DEFAULT_PACKAGE_VERSION} + - git tag v$PACKAGE_VERSION && git push origin v$PACKAGE_VERSION + - dotnet pack -c $CONFIGURATION -p:PackageVersion=$PACKAGE_VERSION +deploy: + provider: releases + name: v$PACKAGE_VERSION + token: $GITHUB_OAUTH_TOKEN + cleanup: true + repo: ZEXSM/Swagger.Documentation + on: + branch: main +after_deploy: + - dotnet nuget push ./src/Swagger.Documentation/bin/Release/Swagger.Documentation.$PACKAGE_VERSION.nupkg -k $NUGET_API_KEY -s $NUGET_SOURCE \ No newline at end of file diff --git a/README.md b/README.md index 5c16554..2abbfa0 100644 --- a/README.md +++ b/README.md @@ -1 +1,61 @@ -# Swagger.Documentation \ No newline at end of file +# Swagger.Documentation +The library allows you to embed and render documentation from Markdown files + +[![Build Status](https://travis-ci.com/ZEXSM/Swagger.Documentation.svg?branch=main)](https://travis-ci.com/ZEXSM/Swagger.Documentation) +[![Coverage Status](https://coveralls.io/repos/github/ZEXSM/Swagger.Documentation/badge.svg?branch=master)](https://coveralls.io/github/ZEXSM/Swagger.Documentation?branch=master) +[![Nuget Status](https://img.shields.io/nuget/dt/Swagger.Documentation.svg)](https://www.nuget.org/packages/Swagger.Documentation) + +## Benefits +Display documentation from Markdown files +![example](example.png) + + +## Installation +To install `Swagger.Documentation` from `Visual Studio`, find `Swagger.Documentation` in the `NuGet` package manager user interface or enter the following command in the package manager console: +``` +Install-Package Swagger.Documentation +``` + +To add a link to the main dotnet project, run the following command line: +``` +dotnet add package Swagger.Documentation +``` + +## Usage +1. Add support and download Markdown file + ```csharp + public void ConfigureServices(IServiceCollection services) + { + ... + services.AddSwaggerGen(options => + { + ... + options.OperationFilter(); + ... + }); + ... + } + public void Configure(IApplicationBuilder app, IWebHostEnvironment env) + { + ... + app.UseSwaggerUISupportMarkdown(); + ... + } + ``` +2. To display documentation in Swagger, you must use one of the structures + 1. Documentation structure for a service without versioning + * **/ApiDocs** (*reserved directory name*) + * **/Resource name** (without the word `Controller`) + * **/Diagrams** (*reserved directory name*. Diagrams related to any of the resource operations/methods) + * **/Name of the operation** (if absent, the method name is used) + * **Diagrams** (Optional diagrams reflecting the overall process. Here you can also place diagrams that will be displayed in `README.md`) + * **Other directories** + + 2. Documentation structure for a versioned service + * **/ApiDocs** (*reserved directory name*) + * **/Resource name** (without the word `Controller`) + * **/Version** (The name must be specified based on the format of the version. Usually it is `V1`) + * **/Diagrams** (*reserved directory name*. Diagrams related to any of the resource operations/methods) + * **/Name of the operation** (if absent, the method name is used) + * **Diagrams** (Optional diagrams reflecting the overall process. Here you can also place diagrams that will be displayed in `README.md`) + * **Other directories**