Skip to content

improve swagger #775

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

improve swagger #775

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 95 additions & 0 deletions src/applications/mixcore/Controllers/PageContentApiController.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,26 @@
using Mix.Services.Databases.Lib.Interfaces;
using Mix.Shared.Models;
using Mix.SignalR.Interfaces;
using System.Net;
using Swashbuckle.AspNetCore.Annotations;

namespace Mixcore.Controllers
{
/// <summary>
/// API controller for managing page content operations
/// </summary>
[Route("api/v2/rest/mixcore/page-content")]
[ApiController]
[Produces("application/json")]
[SwaggerTag("Page Content Management")]
public sealed class PageContentApiController : MixQueryApiControllerBase<PageContentViewModel, MixCmsContext, MixPageContent, int>
{
private readonly IMixMetadataService _metadataService;
private readonly IMixDbDataService _mixDbDataService;

/// <summary>
/// Constructor for PageContentApiController
/// </summary>
public PageContentApiController(
IHttpContextAccessor httpContextAccessor,
IConfiguration configuration,
Expand All @@ -35,11 +47,94 @@ public PageContentApiController(
_mixDbDataService = mixDbDataService;
}

/// <summary>
/// Retrieves a specific page content by its identifier
/// </summary>
/// <param name="id">The page content identifier</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The page content details</returns>
[SwaggerResponse((int)HttpStatusCode.OK, "Successfully retrieved page content", typeof(PageContentViewModel))]
[SwaggerResponse((int)HttpStatusCode.NotFound, "Page content not found")]
protected override async Task<PageContentViewModel> GetById(int id, CancellationToken cancellationToken = default)
{
var result = await base.GetById(id, cancellationToken);
await result.LoadDataAsync(_mixDbDataService, _metadataService, new(), CacheService);
return result;
}

/// <summary>
/// Gets a paginated list of page content items
/// </summary>
/// <param name="request">Search and pagination parameters</param>
/// <returns>Paginated list of page content items</returns>
[HttpGet]
[SwaggerOperation(
Summary = "Get paginated page content items",
Description = "Retrieves a paginated list of page content items based on search criteria",
OperationId = "GetPageContent",
Tags = new[] { "Page Content" }
)]
[SwaggerResponse((int)HttpStatusCode.OK, "Successfully retrieved page content items", typeof(PagingResponseModel<PageContentViewModel>))]
[SwaggerResponse((int)HttpStatusCode.BadRequest, "Invalid request parameters")]
public override async Task<ActionResult<PagingResponseModel<PageContentViewModel>>> Get([FromQuery] SearchRequestDto request)
{
return await base.Get(request);
}

/// <summary>
/// Filters page content items based on criteria
/// </summary>
/// <param name="request">Filter and pagination parameters</param>
/// <returns>Filtered and paginated list of page content items</returns>
[HttpPost("filter")]
[SwaggerOperation(
Summary = "Filter page content items",
Description = "Filters page content items based on specified criteria",
OperationId = "FilterPageContent",
Tags = new[] { "Page Content" }
)]
[SwaggerResponse((int)HttpStatusCode.OK, "Successfully filtered page content items", typeof(PagingResponseModel<PageContentViewModel>))]
[SwaggerResponse((int)HttpStatusCode.BadRequest, "Invalid filter parameters")]
public override async Task<ActionResult<PagingResponseModel<PageContentViewModel>>> Filter([FromBody] SearchRequestDto request)
{
return await base.Filter(request);
}

/// <summary>
/// Gets a specific page content by ID
/// </summary>
/// <param name="id">The page content identifier</param>
/// <returns>The page content details</returns>
[HttpGet("{id}")]
[SwaggerOperation(
Summary = "Get page content by ID",
Description = "Retrieves a specific page content by its unique identifier",
OperationId = "GetPageContentById",
Tags = new[] { "Page Content" }
)]
[SwaggerResponse((int)HttpStatusCode.OK, "Successfully retrieved page content", typeof(PageContentViewModel))]
[SwaggerResponse((int)HttpStatusCode.NotFound, "Page content not found")]
public override async Task<ActionResult<PageContentViewModel>> GetSingle(int id)
{
return await base.GetSingle(id);
}

/// <summary>
/// Gets a default page content template
/// </summary>
/// <returns>A default page content object</returns>
[HttpGet("default")]
[SwaggerOperation(
Summary = "Get default page content template",
Description = "Retrieves a default page content object with initialized values",
OperationId = "GetDefaultPageContent",
Tags = new[] { "Page Content" }
)]
[SwaggerResponse((int)HttpStatusCode.OK, "Successfully retrieved default page content", typeof(PageContentViewModel))]
[SwaggerResponse((int)HttpStatusCode.BadRequest, "Error creating default page content")]
public override async Task<ActionResult<PageContentViewModel>> GetDefaultAsync()
{
return await base.GetDefaultAsync();
}
}
}
104 changes: 103 additions & 1 deletion src/applications/mixcore/Controllers/PostContentApiController.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,18 +11,30 @@
using Mix.Services.Databases.Lib.Interfaces;
using Mix.Shared.Models;
using Mix.SignalR.Interfaces;
using System.Net;
using Swashbuckle.AspNetCore.Annotations;

namespace Mixcore.Controllers
{
/// <summary>
/// API controller for managing post content operations
/// </summary>
[EnableCors(MixCorsPolicies.PublicApis)]
[Route("api/v2/rest/mixcore/post-content")]
[ApiController]
[Produces("application/json")]
[SwaggerTag("Post Content Management")]
public sealed class PostContentApiController : MixQueryApiControllerBase<PostContentViewModel, MixCmsContext, MixPostContent, int>
{
private readonly IMixDbDataService _mixDbDataService;
private readonly RepoDbRepository _repoDbRepository;
private readonly RepoDbRepository _mixRepoDbRepository;
private readonly IMixMetadataService _metadataService;
private readonly MixcorePostService _postService;

/// <summary>
/// Constructor for PostContentApiController
/// </summary>
public PostContentApiController(
IHttpContextAccessor httpContextAccessor,
IConfiguration configuration,
Expand All @@ -45,7 +57,14 @@ public PostContentApiController(
_mixDbDataService = mixDbDataService;
}


/// <summary>
/// Searches for post content based on the provided criteria
/// </summary>
/// <param name="req">Search request parameters</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>Paged list of post content items</returns>
[SwaggerResponse((int)HttpStatusCode.OK, "Successfully retrieved post content items", typeof(PagingResponseModel<PostContentViewModel>))]
[SwaggerResponse((int)HttpStatusCode.BadRequest, "Invalid request parameters")]
protected override async Task<PagingResponseModel<PostContentViewModel>> SearchHandler(SearchRequestDto req, CancellationToken cancellationToken = default)
{
var searchPostQuery = new SearchPostQueryModel(Request, req, CurrentTenant.Id);
Expand All @@ -59,11 +78,94 @@ protected override async Task<PagingResponseModel<PostContentViewModel>> SearchH
return RestApiService.ParseSearchResult(req, result);
}

/// <summary>
/// Retrieves a specific post content by its identifier
/// </summary>
/// <param name="id">The post content identifier</param>
/// <param name="cancellationToken">Cancellation token</param>
/// <returns>The post content details</returns>
[SwaggerResponse((int)HttpStatusCode.OK, "Successfully retrieved post content", typeof(PostContentViewModel))]
[SwaggerResponse((int)HttpStatusCode.NotFound, "Post content not found")]
protected override async Task<PostContentViewModel> GetById(int id, CancellationToken cancellationToken = default)
{
var result = await base.GetById(id);
await result.LoadAdditionalDataAsync(_mixDbDataService, _metadataService, CacheService, cancellationToken);
return result;
}

/// <summary>
/// Gets a paginated list of post content items
/// </summary>
/// <param name="request">Search and pagination parameters</param>
/// <returns>Paginated list of post content items</returns>
[HttpGet]
[SwaggerOperation(
Summary = "Get paginated post content items",
Description = "Retrieves a paginated list of post content items based on search criteria",
OperationId = "GetPostContent",
Tags = new[] { "Post Content" }
)]
[SwaggerResponse((int)HttpStatusCode.OK, "Successfully retrieved post content items", typeof(PagingResponseModel<PostContentViewModel>))]
[SwaggerResponse((int)HttpStatusCode.BadRequest, "Invalid request parameters")]
public override async Task<ActionResult<PagingResponseModel<PostContentViewModel>>> Get([FromQuery] SearchRequestDto request)
{
return await base.Get(request);
}

/// <summary>
/// Filters post content items based on criteria
/// </summary>
/// <param name="request">Filter and pagination parameters</param>
/// <returns>Filtered and paginated list of post content items</returns>
[HttpPost("filter")]
[SwaggerOperation(
Summary = "Filter post content items",
Description = "Filters post content items based on specified criteria",
OperationId = "FilterPostContent",
Tags = new[] { "Post Content" }
)]
[SwaggerResponse((int)HttpStatusCode.OK, "Successfully filtered post content items", typeof(PagingResponseModel<PostContentViewModel>))]
[SwaggerResponse((int)HttpStatusCode.BadRequest, "Invalid filter parameters")]
public override async Task<ActionResult<PagingResponseModel<PostContentViewModel>>> Filter([FromBody] SearchRequestDto request)
{
return await base.Filter(request);
}

/// <summary>
/// Gets a specific post content by ID
/// </summary>
/// <param name="id">The post content identifier</param>
/// <returns>The post content details</returns>
[HttpGet("{id}")]
[SwaggerOperation(
Summary = "Get post content by ID",
Description = "Retrieves a specific post content by its unique identifier",
OperationId = "GetPostContentById",
Tags = new[] { "Post Content" }
)]
[SwaggerResponse((int)HttpStatusCode.OK, "Successfully retrieved post content", typeof(PostContentViewModel))]
[SwaggerResponse((int)HttpStatusCode.NotFound, "Post content not found")]
public override async Task<ActionResult<PostContentViewModel>> GetSingle(int id)
{
return await base.GetSingle(id);
}

/// <summary>
/// Gets a default post content template
/// </summary>
/// <returns>A default post content object</returns>
[HttpGet("default")]
[SwaggerOperation(
Summary = "Get default post content template",
Description = "Retrieves a default post content object with initialized values",
OperationId = "GetDefaultPostContent",
Tags = new[] { "Post Content" }
)]
[SwaggerResponse((int)HttpStatusCode.OK, "Successfully retrieved default post content", typeof(PostContentViewModel))]
[SwaggerResponse((int)HttpStatusCode.BadRequest, "Error creating default post content")]
public override async Task<ActionResult<PostContentViewModel>> GetDefaultAsync()
{
return await base.GetDefaultAsync();
}
}
}
2 changes: 2 additions & 0 deletions src/applications/mixcore/mixcore.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@
<RunAnalyzersDuringLiveAnalysis>False</RunAnalyzersDuringLiveAnalysis>
<RunAnalyzersDuringBuild>False</RunAnalyzersDuringBuild>
<AnalysisLevel>none</AnalysisLevel>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

<ItemGroup>
Expand Down
103 changes: 96 additions & 7 deletions src/applications/mixcore/wwwroot/mix-app/css/swagger.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,17 +13,106 @@
.topbar{
display: none;
}

/* Improve the API endpoint sections */
.swagger-ui .opblock-tag {
font-size: 18px;
/* color: #3b4151;
font-family: sans-serif;
margin: 0 0 5px;
background: #333;*/
margin: 12px 0;
padding: 10px;
border-radius: 4px;
transition: all 0.3s ease;
}

.swagger-ui .opblock-tag-section {
margin-bottom: 16px;
}

.swagger-ui .opblock {
margin: 0 0 15px;
border-radius: 6px;
box-shadow: 0 2px 6px rgba(0, 0, 0, 0.1);
}

/* Improve the GET, POST, PUT, DELETE method coloring */
.swagger-ui .opblock-get {
border-color: #61affe;
background: rgba(97, 175, 254, 0.1);
}

.swagger-ui .opblock-post {
border-color: #49cc90;
background: rgba(73, 204, 144, 0.1);
}

.swagger-ui .opblock-put {
border-color: #fca130;
background: rgba(252, 161, 48, 0.1);
}

.swagger-ui .opblock-delete {
border-color: #f93e3e;
background: rgba(249, 62, 62, 0.1);
}

/* Improve typography */
.swagger-ui, .swagger-ui .opblock-tag, .swagger-ui .opblock .opblock-summary-operation-id,
.swagger-ui .opblock .opblock-summary-path, .swagger-ui .opblock-description-wrapper p,
.swagger-ui .response-col_status, .swagger-ui table thead tr td,
.swagger-ui table thead tr th, .swagger-ui .parameter__name,
.swagger-ui .tab {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif;
}

/* Improve the model schema display */
.swagger-ui .model-box {
padding: 12px;
border-radius: 4px;
background: rgba(0, 0, 0, 0.02);
}

.swagger-ui .model-title {
font-size: 16px;
font-weight: 600;
}

/* Improve the response section */
.swagger-ui .responses-table {
border-radius: 4px;
overflow: hidden;
}

.swagger-ui .response-col_status {
font-weight: 600;
}

/* Add hover effects */
.swagger-ui .opblock:hover {
box-shadow: 0 4px 10px rgba(0, 0, 0, 0.15);
}
.opblock-tag-section.is-open h3{

/* Improve tag section when open */
.opblock-tag-section.is-open h3 {
color: #fff;
background: #333;
border-radius: 4px;
padding: 10px;
}

/* Improve the authorize button */
.swagger-ui .btn.authorize {
border-color: #49cc90;
color: #49cc90;
transition: all 0.3s ease;
}
.swagger-ui .opblock-tag:hover {
color: #333;

.swagger-ui .btn.authorize:hover {
background-color: #49cc90;
color: #fff;
}

/* Make operation summaries more readable */
.swagger-ui .opblock .opblock-summary-description {
font-size: 14px;
color: #3b4151;
padding: 0 8px;
}
Loading
Loading