We want to use grape swagger to document the REST API in the [OpenAPI V2 (swagger)](https://swagger.io/specification/v2/) format. This epic is for collecting all issues related to - General discussions about OpenAPI V2 - Tooling to auto generate the OpenAPI V2 documentation - Annotating API endpoints This epic only focuses on auto generating an OpenAPI V2 documentation. There is also https://gitlab.com/groups/gitlab-org/-/epics/5792 which focuses on automate the markdown documentation using OpenAPI All outstanding questions about this effort can be asked in the #wg_fedramp on Slack ### Why is this needed? This is critical to the DAST requirement for FedRAMP. We need an OpenAPI documentation that is as close to completion as possible by Nov. 17, 2022 to give AppSec enough time to [integrate it into DAST](https://gitlab.com/gitlab-org/gitlab/-/issues/372422). The scan results from DAST will then identify ~"FedRAMP Milestone::Vuln Remediation" ### Prioritization guidance See [internal note below](https://gitlab.com/groups/gitlab-org/-/epics/8926#note_1146998525). ### Availability & Testing There is currently a [contract testing effort](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/contracts/README.md) in the GitLab project happening using Pact. suggestion: explore using the Pact tool to test a generated OpenAPI specification. related: https://bitbucket.org/atlassian/swagger-mock-validator/src/master/ <!-- This section needs to be retained and filled in during the workflow planning breakdown phase of this feature proposal, if not earlier. What risks does this change pose to our availability? How might it affect the quality of the product? What additional test coverage or changes to tests will be needed? Will it require cross-browser testing? Please list the test areas (unit, integration and end-to-end) that needs to be added or updated to ensure that this feature will work as intended. Please use the list below as guidance. * Unit test changes * Integration test changes * End-to-end test change See the Quality Engineering quad planning and test planning processes and reach out to your counterpart Software Engineer in Test for assistance. Quad Planning: https://about.gitlab.com/handbook/engineering/quality/quality-engineering/quad-planning Test Planning: https://about.gitlab.com/handbook/engineering/quality/quality-engineering/test-engineering/#test-planning --> ### Dashboard and stats - [Development Workflow Dashboard](https://gitlab.com/groups/gitlab-org/-/boards/363876?label_name[]=openapi&label_name[]=FedRAMP) - Stats https://gitlab.com/groups/gitlab-org/-/epics/8926#note_1167800675 ### Effort by group | Group | Status | Issues | |--------------|---------|---------------| | ~"group::source code" | 23 issues | [issues](https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=group%3A%3Asource%20code&label_name%5B%5D=openapi&label_name%5B%5D=FedRAMP&first_page_size=20) | | ~"group::integrations" | 6 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Aintegrations&label_name%5B%5D=FedRAMP&first_page_size=20) | | ~"group::global search" | 2 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Aglobal%20search&first_page_size=20) | | ~"group::release" | 14 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Arelease&first_page_size=20) | | ~"group::configure" | 8 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Aconfigure&first_page_size=20) | | ~"group::optimize" | 4 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Aoptimize&first_page_size=20) | | ~"group::authentication and authorization" | 11 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Aauthentication%20and%20authorization&first_page_size=20) | | ~"group::utilization" | 1 issue | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Autilization&first_page_size=20) | | ~"group::gitaly" | 3 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Agitaly&first_page_size=20) | | ~"group::threat insights" | 4 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Athreat%20insights&first_page_size=20) | | ~"group::project management" | 21 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Aproject%20management&first_page_size=20) | | ~"group::product planning" | 4 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Aproduct%20planning&first_page_size=20) | | ~"group::product analytics" | 1 issue | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Aproduct%20analytics&first_page_size=20) | | ~"group::pipeline execution" | 6 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Apipeline%20execution&label_name%5B%5D=FedRAMP&first_page_size=20) | ~"group::container registry" | 5 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Acontainer%20registry&label_name%5B%5D=FedRAMP&first_page_size=20) | ~"group::package registry" | 21 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Apackage%20registry&label_name%5B%5D=FedRAMP&first_page_size=20) | ~"group::compliance" | 2 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=FedRAMP&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Acompliance&first_page_size=100) | ~"group::workspace" | 11 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=FedRAMP&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Aworkspace&first_page_size=100) | ~"group::code review" | 3 issues | [issues](https://gitlab.com/gitlab-org/gitlab/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=group%3A%3Acode%20review&label_name%5B%5D=openapi&first_page_size=20) | ~"group::pipeline authoring" | 4 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Apipeline%20authoring&label_name%5B%5D=FedRAMP&first_page_size=20) | ~"group::geo" | 3 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=openapi&label_name%5B%5D=group%3A%3Ageo&label_name%5B%5D=FedRAMP&first_page_size=20) | ~"group::import" | 7 issues | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=all&label_name%5B%5D=openapi&label_name%5B%5D=FedRAMP&label_name%5B%5D=group%3A%3Aimport&first_page_size=20) | ~"group::not_owned" | 5 issue | [issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=weight_desc&state=opened&label_name%5B%5D=FedRAMP&label_name%5B%5D=openapi&not%5Blabel_name%5D%5B%5D=group%3A%3A%2a&first_page_size=20) | ## Examples https://gitlab.com/groups/gitlab-org/-/epics/8926#note_1149802328 ### :tv: Video guide - [How to add OpenAPI documentation](https://www.youtube.com/watch?v=V1hUlFOBbYY) created by @vyaklushin ## FAQ <details><summary>We don't have capacity to work on this. Is this a requirement?</summary> We want to cover as many endpoints as possible until late November. This comment describes it with more details: https://gitlab.com/groups/gitlab-org/-/epics/8926#note_1146998525 </details> ### Technical FAQ <details><summary>Do we need to include response examples</summary> No, if the `success` or `failure` response has a model. That's good enough. Examples are nice but not needed for Fuzz testing. Here is an example for a response model definition: ```ruby success EE::API::Entities::GroupPushRule ``` </details> <details><summary>Is there an example, MR for an EE endpoint?</summary> Yes: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102168/diffs </details>16