Add comprehensive documentation and runnable sample applications

[Copilot]

Documentation and Samples Implementation Plan

• 1. Enable XML documentation generation in MiniJwt.Core.csproj
• 2. Create docs directory structure
  • docs/getting-started.md
  • docs/configuration.md
  • docs/examples.md
  • docs/faq.md
• 3. Create samples directory with runnable projects
  • samples/ConsoleMinimal/ (basic token create/validate)
  • samples/ASPNetCoreAuth/ (DI + authentication integration)
  • samples/WorkerService/ (BackgroundService example)
• 4. Update README.md with links to docs and samples
• 5. Update CI workflow to build samples
• 6. Verify all samples build and run correctly
• 7. Code review and security check

Summary

All requirements have been successfully implemented:

✅ XML Documentation: Enabled in csproj, generates for all target frameworks, included in NuGet package
✅ Documentation: 4 comprehensive markdown files covering getting started, configuration, examples, and FAQ
✅ Samples: 3 runnable sample applications (Console, ASP.NET Core, Worker Service) with READMEs
✅ README Updates: Links to docs and samples, improved structure
✅ CI Workflow: Updated to build all samples
✅ Testing: All 25 existing tests pass, samples build and run successfully
✅ Code Review: All feedback addressed
✅ Security: No vulnerabilities detected by CodeQL

The library remains minimal with no breaking changes to the existing API.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Document MiniJwt.Core and add integration samples (docs/ + samples/)</issue_title>
<issue_description>Background / MotivationMiniJwt.Core needs clear, runnable documentation and integration examples so that developers can quickly adopt it in different application types (Console, ASP.NET Core, WorkerService, etc.). The goal is to keep the package minimal and multi‑target compatible while providing easy-to-follow integration patterns.

Goals

• Add user-friendly documentation under docs/ (getting-started, configuration, FAQ).

• Add runnable samples under samples/ for common app types:

• Console (minimal create/validate token)

• ASP.NET Core (DI registration + authentication integration)

• WorkerService / BackgroundService

• Ensure samples build on the supported target frameworks (multi-target).

• Include XML docs in the NuGet package.

• Keep MiniJwt.Core minimal; push optional features into separate extension packages if needed.

Deliverables

• docs/getting-started.md

• docs/configuration.md

• docs/examples.md (links and short explanations)

• docs/faq.md (security best practices: key management, rotation)

• samples/ConsoleMinimal/Program.cs

• samples/ASPNetCoreAuth/ (Program.cs or Startup with AddMiniJwt usage and auth config)

• samples/WorkerService/ (IHostedService example)

• Update README.md to link to docs/ and samples/

• Add a light CI workflow that builds samples and the library across supported TFs

• Add XML doc generation setting and ensure XML file is included in nupkg

Proposed repo structure

• docs/

• getting-started.md

• configuration.md

• examples.md

• faq.md

• samples/

• ConsoleMinimal/

• ASPNetCoreAuth/

• WorkerService/

• src/

• MiniJwt.Core/

• tests/

• MiniJwt.Core.Tests/

• .github/workflows/ci.yml

• README.md

• CHANGELOG.md

Suggested minimal API snippets to include in docs (adjust to current codebase)

1. Public API surface (recommended)public interface IJwtService{string CreateToken(object claimsOrPayload);ClaimsPrincipal ValidateToken(string token);}

public class JwtOptions{public string Issuer { get; set; }public string Audience { get; set; }public string SigningKey { get; set; } // encourage using IKeyProvider in advanced setupspublic TimeSpan TokenLifetime { get; set; } = TimeSpan.FromHours(1);}

public static class ServiceCollectionExtensions{public static IServiceCollection AddMiniJwt(this IServiceCollection services, Action configure){// register IJwtService and options}}

2. Minimal Console sample (samples/ConsoleMinimal/Program.cs)var options = new JwtOptions { Issuer = “my”, Audience = “api”, SigningKey = “super-secret”, TokenLifetime = TimeSpan.FromHours(1) };var jwtService = new JwtService(options);var token = jwtService.CreateToken(new { sub = “user1”, role = “admin” });Console.WriteLine(“Token: “ + token);var principal = jwtService.ValidateToken(token);Console.WriteLine(“Principal: “ + principal?.Identity?.Name);

3. ASP.NET Core integration (Program.cs)builder.Services.AddMiniJwt(opts =>{opts.Issuer = Configuration[“Jwt:Issuer”];opts.Audience = Configuration[“Jwt:Audience”];opts.SigningKey = Configuration[“Jwt:SigningKey”];});builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme).AddJwtBearer(options =>{// configure to use MiniJwt.Core validation or use IJwtService inside an events handler});

Checklist

• Create docs/ files (getting-started, configuration, examples, faq)

• Create samples/ ConsoleMinimal, ASPNetCoreAuth, WorkerService

• Add XML doc comments and enable XML generation in csproj

• Ensure src project is multi-targeted (e.g., netstandard2.0;net6.0;net8.0) or appropriate TFs

• Add tests project with basic create/validate tests and multi-target test matrix

• Add GitHub Actions workflow to build/test/pack across TFs and build samples

• Update README with links and badges (docs/CI)

• Document public stable API surface in docs

• Optionally split optional features into extension packages

Acceptance criteria

• docs/getting-started.md explains installation and includes a working example

• At least 3 runnable samples are present and build locally via dotnet run

• CI validates builds for the supported target frameworks

• README contains links to docs and samples

• NuGet package contains XML docs

Labels

• documentation

• enhancement

• good first issue (if splitting into subtasks)

• help wanted

Assignees / Milestone

• Suggested assignee: @jeanlrnt (or leave unassigned to accept community contributions)

• Milestone: “Docs & Samples”

Notes for implementer

• Keep MiniJwt.Core minimal; avoid adding heavy dependencies. If a dependency is needed, move it to an extension package (e.g., MiniJwt.Extensions.Json).

• Prefer System.* APIs and dependency injection friendly patterns.

• Show best practices for key management and rotation in the docs.

• Multi-target the project to cover older and newer consumers.</issue_descr...

• Fixes Document MiniJwt.Core and add integration samples (docs/ + samples/) #18

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

This PR adds comprehensive documentation and runnable sample applications to the MiniJwt.Core library, addressing issue #18. The implementation provides developers with clear getting-started guides, configuration documentation, practical examples, and three different sample applications demonstrating integration patterns.

Key Changes

• XML Documentation: Enabled documentation file generation in MiniJwt.Core.csproj for inclusion in the NuGet package
• Documentation Suite: Added four comprehensive markdown files (getting-started.md, configuration.md, examples.md, faq.md) covering installation, usage, and best practices
• Sample Applications: Created three runnable sample projects demonstrating console, ASP.NET Core, and worker service integration scenarios

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/MiniJwt.Core/MiniJwt.Core.csproj	Enables XML documentation generation for NuGet package inclusion
docs/getting-started.md	Installation guide and quick start examples with common troubleshooting
docs/configuration.md	Detailed configuration options and environment-specific setup patterns
docs/examples.md	Code examples for various integration scenarios with runnable sample links
docs/faq.md	Comprehensive FAQ covering general, security, integration, and troubleshooting topics
samples/ConsoleMinimal/	Minimal console application demonstrating basic token generation and validation
samples/ASPNetCoreAuth/	Full ASP.NET Core web API with JWT authentication, protected endpoints, and role-based authorization
samples/WorkerService/	Background service example with periodic token generation and validation
README.md	Updated with documentation links, sample application descriptions, and improved support section
.github/workflows/ci.yml	Added sample project builds to CI pipeline for validation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.