View Issue Details

WikiRelated ChangesetsJump to Notes
IDProjectCategoryView StatusDate SubmittedLast Update
0034823mantisbtapi restpublic2024-10-05 20:252025-12-29 20:30
Reportervboctor Assigned Tovboctor  
PrioritynormalSeverityfeatureReproducibilityN/A
Status closedResolutionfixed 
Product Version2.27.0 
Target Version2.28.0Fixed in Version2.28.0 
Summary0034823: Create an OpenAPI Description for REST API
Description

I have been looking for a good setup for API definitions that is open source friendly and enables teams to collaborate and came to the conclusion that it is the best option to maintain an Open API file.

The reasons are:

  • There is a good ecosystem around OpenAPI specifications, whether it is to generate documentation or clients in different languages.
  • Tools for REST API don't always have a good export for documentation (e.g. Bruno - https://usebruno.com).
  • Tools don't have a good implementation for export to OpenAPI (applies to both Bruno and Postman).
  • Bruno has export to OpenAPI behind a paywall.
  • Tools like Postman and Bruno have good import from OpenAPI.
  • It is easy for Postman to push changes to their services that were meant for local testing.

Having a hand crafted OpenAPI file is much better than a tool generated one. It is like HTML generated by dome GUI API vs. one written by hand. It is much more intentional and cleaner. Specially when it comes to aspects like defining schema of payloads where OpenAPI is much more specific, but such tools don't typically apply such concept.

TagsNo tags attached.

Activities

vboctor

vboctor

2024-10-05 20:32

manager   ~0069304

PR: https://github.com/mantisbt/mantisbt/pull/2032
dregad

dregad

2024-10-06 04:48

developer   ~0069305

At last... THANK YOU for this !

I had started work on such conversion 3-4 years ago, I probably have a work-in-progress branch lying around somewhere. I'll look it up and see if I can make any contributions, let me know once your PR is in a reviewable state.
dregad

dregad

2024-10-06 05:26

developer   ~0069306

Found it - https://github.com/dregad/mantisbt/tree/openapi

This goes back to February 2021, so probably not worth going into detail since the API changed quite a bit since then. Just here for the record. I added some review comments to the PR, which reflect the changes I made back then.

Related Changesets

MantisBT: master 8dda5234

2024-10-05 20:28

vboctor


Details Diff		 OpenAPI: Initial version of OpenAPI file

Fixes 0034823		 Affected Issues
0034823
add - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 457e5aa0

2024-10-05 20:54

vboctor


Details Diff		 OpenAPI: Use proper annotation for OpenAPI ApiKey authorization

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master c007ba90

2024-10-05 21:03

vboctor


Details Diff		 OpenAPI: Don't pass Content-Type as a parameter

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 6ea7d767

2024-10-05 21:34

vboctor


Details Diff		 OpenAPI: Update operation ids and remove `minimal` operations

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 51d29a13

2024-10-05 21:58

vboctor


Details Diff		 OpenAPI: Add 4XX response codes

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 833c219f

2024-10-05 21:59

vboctor


Details Diff		 OpenAPI: Add license

Fixes 0034823

OpenAPI: Update License

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master ab42a096

2024-10-06 01:01

vboctor


Details Diff		 OpenAPI: Remove query strings from API paths + fix `in` values

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 3a44236f

2024-10-06 15:34

vboctor


Details Diff		 OpenAPI: Add file header to OpenAPI spec

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master ce80ec47

2024-10-06 15:35

vboctor


Details Diff		 OpenAPI: Add description element

Fixes 0034823

OpenAPI: Update Description

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 2c197763

2024-10-06 15:36

vboctor


Details Diff		 OpenAPI: Update Get Issues API description

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master d08f9771

2024-10-06 15:44

vboctor


Details Diff		 OpenAPI: Remove index properties + add some re-usable types

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master a9878f06

2024-10-06 16:06

vboctor


Details Diff		 OpenAPI: Make `issue_id` parameter definition a re-usable component

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master e322f446

2024-10-06 16:09

vboctor


Details Diff		 OpenAPI: Make `filter_id` parameter definition a re-usable component

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 112da96d

2024-10-06 16:22

vboctor


Details Diff		 OpenAPI: Make `user_id` parameter definition a re-usable component

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 78b029d5

2024-10-06 17:08

vboctor


Details Diff		 OpenAPI: Add custom instance endpoint to `servers`

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 914348d3

2024-10-06 17:09

vboctor


Details Diff		 OpenAPI: Added `contact` meta-data

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 64f5041c

2024-10-06 17:18

vboctor


Details Diff		 OpenAPI: Update version from `3.0.0` to `3.0.3`

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 36822a04

2024-10-06 17:55

vboctor


Details Diff		 OpenAPI: Add re-usable standard/basic responses and reference them

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 7bf734c7

2024-10-06 18:03

vboctor


Details Diff		 OpenAPI: re-order API definitions to have it as parameters, request, and then response

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 4562e2b9

2024-10-06 18:11

vboctor


Details Diff		 OpenAPI: Make `project_id` parameter definition a re-usable component

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 90fce152

2024-10-06 18:35

vboctor


Details Diff		 OpenAPI: Update re-usable schema for requests

Fixes 0034823		 Affected Issues
0034823
mod - api/rest/mantisbt_openapi.yaml Diff File

MantisBT: master 1b009721

2025-12-14 20:00

vboctor

Committer: community


Details Diff		 Merge pull request 0002032 from vboctor/issue34823_openapi

REST API OpenAPI Spec

Fixes 0034823		 Affected Issues
0034823
add - api/rest/mantisbt_openapi.yaml Diff File