Nemcio/SCM-Manager
1
0
Fork 0
mirror of https://github.com/scm-manager/scm-manager.git synced 2026-01-28 02:09:09 +01:00
Code Issues Packages Projects Releases Activity

Generate openapi spec for scm-webapp

Browse Source
This commit is contained in:
Sebastian Sdorra
2021-01-07 10:04:09 +01:00
committed by René Pfeuffer
parent 55507b3f35
commit ee879b7fb0
3 changed files with 55 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
scm-webapp/build.gradle
View File

@@ -136,7 +136,10 @@ dependencies {
war {
from 'build/war'
from project.configurations.assets
dependsOn 'copy-core-plugins'
into('WEB-INF/classes/META-INF/scm') {
from('build/openapi')
}
dependsOn 'copy-core-plugins', 'resolve'
}
artifacts {
@@ -161,9 +164,28 @@ serve {
dependsOn 'dev-war'
}
resolve {
outputFileName = 'openapi'
outputFormat = 'JSONANDYAML'
prettyPrint = 'TRUE'
classpath = sourceSets.main.runtimeClasspath
resourcePackages = ['sonia.scm.api.v2.resources']
outputDir = file('build/openapi')
openApiFile = file('build/tmp/openapi.yml')
}
task prepareOpenAPI(type: Copy) {
from 'src/main/doc/openapi.yml'
into 'build/tmp'
expand(version: project.version)
}
tasks.getByName("resolve").configure {
dependsOn 'prepareOpenAPI'
}
/**
WTF???
<!-- fix javadoc -->
<dependency>
@@ -182,55 +204,8 @@ fix java.lang.NoClassDefFoundError org/w3c/dom/ElementTraversal
<artifactId>xml-apis</artifactId>
<version>1.4.01</version>
</dependency>
<!-- core plugins -->
<dependency>
<groupId>sonia.scm.plugins</groupId>
<artifactId>scm-git-plugin</artifactId>
<version>2.13.0-SNAPSHOT</version>
<classifier>tests</classifier>
<scope>test</scope>
</dependency>
<dependency>
<groupId>sonia.scm.plugins</groupId>
<artifactId>scm-git-plugin</artifactId>
<version>2.13.0-SNAPSHOT</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>sonia.scm.plugins</groupId>
<artifactId>scm-hg-plugin</artifactId>
<version>2.13.0-SNAPSHOT</version>
<classifier>tests</classifier>
<scope>test</scope>
</dependency>
<dependency>
<groupId>sonia.scm.plugins</groupId>
<artifactId>scm-hg-plugin</artifactId>
<version>2.13.0-SNAPSHOT</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>sonia.scm.plugins</groupId>
<artifactId>scm-svn-plugin</artifactId>
<version>2.13.0-SNAPSHOT</version>
<classifier>tests</classifier>
<scope>test</scope>
</dependency>
<dependency>
<groupId>sonia.scm.plugins</groupId>
<artifactId>scm-svn-plugin</artifactId>
<version>2.13.0-SNAPSHOT</version>
<scope>test</scope>
</dependency>
**/
test {
useJUnitPlatform()
// TODO integration tests

15
scm-webapp/src/main/doc/openapi.md
View File

@@ -1,15 +0,0 @@
The following REST documentation describes all public endpoints of your SCM-Manager instance.
You can try the endpoints with or without authentication right on the swagger surface provided by the OpenAPI-Plugin.
For authenticated requests please login to the SCM-Manager. You can also use the "Authorize" button and insert your preferred authentication method.
For basic authentication simply use your SCM-Manager credentials. If you want to use the bearer token authentication, you can generate an
valid token using the authentication endpoint and copy the response body.
SCM-Manager defines a modern ["Level 3"-REST API](https://martinfowler.com/articles/richardsonMaturityModel.html).
Using the HATEOAS architecture for REST allows us to provide discoverable and self explanatory endpoint definitions.
The responses are build using the [HAL JSON format](http://stateless.co/hal_specification.html).
HAL makes the API human-friendly and simplifies the communication between the frontend and the server using links and embedded resources.
We highly suggest using HAL links when creating new functions for SCM-Manager since they are consistent and are only
appended to the response when user has the necessary permissions. The links and embedded resources can also be used by plugins, which can
define new resources or enrich existing ones.

30
scm-webapp/src/main/doc/openapi.yml Normal file
View File

@@ -0,0 +1,30 @@
openapi: 3.0.1
info:
title: SCM-Manager REST-API
description: |
The following REST documentation describes all public endpoints of your SCM-Manager instance.
You can try the endpoints with or without authentication right on the swagger surface provided by the OpenAPI-Plugin.
For authenticated requests please login to the SCM-Manager. You can also use the "Authorize" button and insert your preferred authentication method.
For basic authentication simply use your SCM-Manager credentials. If you want to use the bearer token authentication, you can generate an
valid token using the authentication endpoint and copy the response body.
SCM-Manager defines a modern ["Level 3"-REST API](https://martinfowler.com/articles/richardsonMaturityModel.html).
Using the HATEOAS architecture for REST allows us to provide discoverable and self explanatory endpoint definitions.
The responses are build using the [HAL JSON format](http://stateless.co/hal_specification.html).
HAL makes the API human-friendly and simplifies the communication between the frontend and the server using links and embedded resources.
We highly suggest using HAL links when creating new functions for SCM-Manager since they are consistent and are only
appended to the response when user has the necessary permissions. The links and embedded resources can also be used by plugins, which can
define new resources or enrich existing ones.
contact:
name: SCM-Manager
url: https://scm-manager.org
email: scmmanager@googlegroups.com
license:
name: MIT
url: https://github.com/scm-manager/scm-manager/blob/develop/LICENSE.txt
version: ${version}
servers:
- url: http://localhost:8081/scm/api
description: local endpoint url