Improving OpenAPI documentation

This commit is contained in:
Martin Stockhammer 2021-01-05 12:18:26 +01:00
parent 8fd111e515
commit bddef58439
8 changed files with 102 additions and 63 deletions

View File

@ -25,8 +25,6 @@ archivaVersion=${archivaVersion}
log4jVersion=${log4j.version}
slf4jVersion=${slf4j.version}
springVersion=${spring.version}
redbackRegistryVersion=${redback.registry.version}
redbackCacheVersion=${redback.cache.version}
springockitoVersion=${springockito.version}
mockitoVersion=${mockito.version}
httpclientVersion=${httpclient.version}

View File

@ -20,11 +20,13 @@
import javax.xml.bind.annotation.XmlRootElement;
import java.io.Serializable;
import java.util.Objects;
/**
* @author Martin Stockhammer <martin_s@apache.org>
*/
@XmlRootElement(name="beanInformation")
@Schema(name="BeanInformation",description = "Information about a bean instance.")
public class BeanInformation implements Serializable
{
private static final long serialVersionUID = -432385743277355987L;
@ -58,7 +60,7 @@ public void setId( String id )
this.id = id;
}
@Schema(description = "The display name")
@Schema(name="display_name", description = "The display name")
public String getDisplayName( )
{
return displayName;
@ -69,7 +71,7 @@ public void setDisplayName( String displayName )
this.displayName = displayName;
}
@Schema(description = "The translation key for the description")
@Schema(name="description_key", description = "The translation key for the description")
public String getDescriptionKey( )
{
return descriptionKey;
@ -80,7 +82,7 @@ public void setDescriptionKey( String descriptionKey )
this.descriptionKey = descriptionKey;
}
@Schema(description = "The description translated in the default language")
@Schema(name="default_description", description = "The description translated in the default language")
public String getDefaultDescription( )
{
return defaultDescription;
@ -101,4 +103,31 @@ public void setReadonly( boolean readonly )
{
this.readonly = readonly;
}
@Override
public boolean equals( Object o )
{
if ( this == o ) return true;
if ( o == null || getClass( ) != o.getClass( ) ) return false;
BeanInformation that = (BeanInformation) o;
return readonly == that.readonly && id.equals( that.id ) && Objects.equals( displayName, that.displayName ) && Objects.equals( descriptionKey, that.descriptionKey ) && Objects.equals( defaultDescription, that.defaultDescription );
}
@Override
public int hashCode( )
{
return Objects.hash( id, displayName, descriptionKey, defaultDescription, readonly );
}
@Override
public String toString( )
{
return "BeanInformation{" +
"id='" + id + '\'' +
", display_name='" + displayName + '\'' +
", description_key='" + descriptionKey + '\'' +
", default_description='" + defaultDescription + '\'' +
", readonly=" + readonly +
'}';
}
}

View File

@ -29,6 +29,7 @@
* @since 3.0
*/
@XmlRootElement( name = "cacheConfiguration" )
@Schema(name="CacheConfiguration",description = "Cache configuration attributes")
public class CacheConfiguration
implements Serializable
{
@ -67,7 +68,7 @@ public static CacheConfiguration of( org.apache.archiva.admin.model.beans.CacheC
return newConfig;
}
@Schema(description = "The maximum number of seconds an element can exist in the cache without being accessed. "+
@Schema(name="time_to_idle_seconds", description = "The maximum number of seconds an element can exist in the cache without being accessed. "+
"The element expires at this limit and will no longer be returned from the cache.")
public int getTimeToIdleSeconds()
{
@ -79,7 +80,7 @@ public void setTimeToIdleSeconds( int timeToIdleSeconds )
this.timeToIdleSeconds = timeToIdleSeconds;
}
@Schema(description = "The maximum number of seconds an element can exist in the cache regardless of use. "+
@Schema(name="time_to_live_seconds", description = "The maximum number of seconds an element can exist in the cache regardless of use. "+
"The element expires at this limit and will no longer be returned from the cache.")
public int getTimeToLiveSeconds()
{
@ -91,7 +92,7 @@ public void setTimeToLiveSeconds( int timeToLiveSeconds )
this.timeToLiveSeconds = timeToLiveSeconds;
}
@Schema(description = "The maximum cache entries to keep in memory. If the limit is reached, older entries will be evicted, or persisted on disk.")
@Schema(name="max_entries_in_memory", description = "The maximum cache entries to keep in memory. If the limit is reached, older entries will be evicted, or persisted on disk.")
public int getMaxEntriesInMemory()
{
return maxEntriesInMemory;
@ -102,7 +103,7 @@ public void setMaxEntriesInMemory( int maxEntriesInMemory )
this.maxEntriesInMemory = maxEntriesInMemory;
}
@Schema(description = "The maximum cache entries to keep on disk. If the limit is reached, older entries will be evicted.")
@Schema(name="max_entries_on_disk", description = "The maximum cache entries to keep on disk. If the limit is reached, older entries will be evicted.")
public int getMaxEntriesOnDisk()
{
return maxEntriesOnDisk;
@ -142,10 +143,10 @@ public String toString()
{
final StringBuilder sb = new StringBuilder();
sb.append( "CacheConfiguration" );
sb.append( "{timeToIdleSeconds=" ).append( timeToIdleSeconds );
sb.append( ", timeToLiveSeconds=" ).append( timeToLiveSeconds );
sb.append( ", maxElementsInMemory=" ).append( maxEntriesInMemory );
sb.append( ", maxElementsOnDisk=" ).append( maxEntriesOnDisk );
sb.append( "{time_to_idle_seconds=" ).append( timeToIdleSeconds );
sb.append( ", time_to_live_seconds=" ).append( timeToLiveSeconds );
sb.append( ", max_elements_in_memory=" ).append( maxEntriesInMemory );
sb.append( ", max_elements_on_disk=" ).append( maxEntriesOnDisk );
sb.append( '}' );
return sb.toString();
}

View File

@ -29,6 +29,7 @@
* @since 3.0
*/
@XmlRootElement(name="ldapConfiguration")
@Schema(name="LdapConfiguration", description = "LDAP configuration attributes")
public class LdapConfiguration implements Serializable
{
private static final long serialVersionUID = -4736767846016398583L;
@ -66,7 +67,7 @@ public static LdapConfiguration of( org.apache.archiva.admin.model.beans.LdapCon
return newCfg;
}
@Schema(description = "The hostname to use to connect to the LDAP server")
@Schema(name="host_name", description = "The hostname to use to connect to the LDAP server")
public String getHostName( )
{
return hostName;
@ -88,7 +89,7 @@ public void setPort( int port )
this.port = port;
}
@Schema(description = "If SSL should be used for connecting the LDAP server")
@Schema(name="ssl_enabled", description = "If SSL should be used for connecting the LDAP server")
public boolean isSslEnabled( )
{
return sslEnabled;
@ -99,7 +100,7 @@ public void setSslEnabled( boolean sslEnabled )
this.sslEnabled = sslEnabled;
}
@Schema(description = "The BASE DN used for the LDAP server")
@Schema(name="base_dn", description = "The BASE DN used for the LDAP server")
public String getBaseDn( )
{
return baseDn;
@ -110,7 +111,7 @@ public void setBaseDn( String baseDn )
this.baseDn = baseDn == null ? "" : baseDn;
}
@Schema(description = "The distinguished name of the bind user which is used to bind to the LDAP server")
@Schema(name="bind_dn", description = "The distinguished name of the bind user which is used to bind to the LDAP server")
public String getBindDn( )
{
return bindDn;
@ -121,7 +122,7 @@ public void setBindDn( String bindDn )
this.bindDn = bindDn == null ? "" : bindDn;
}
@Schema(description = "The password used to bind to the ldap server")
@Schema(name="bind_password", description = "The password used to bind to the ldap server")
public String getBindPassword( )
{
return bindPassword;
@ -132,7 +133,7 @@ public void setBindPassword( String bindPassword )
this.bindPassword = bindPassword==null?"":bindPassword;
}
@Schema(description = "The distinguished name of the base to use for searching group.")
@Schema(name="groups_base_dn", description = "The distinguished name of the base to use for searching group.")
public String getGroupsBaseDn( )
{
return groupsBaseDn;
@ -143,7 +144,7 @@ public void setGroupsBaseDn( String groupsBaseDn )
this.groupsBaseDn = groupsBaseDn==null?"":groupsBaseDn;
}
@Schema(description = "The authentication method used to bind to the LDAP server (PLAINTEXT, SASL, ...)")
@Schema(name="authentication_method", description = "The authentication method used to bind to the LDAP server (PLAINTEXT, SASL, ...)")
public String getAuthenticationMethod( )
{
return authenticationMethod;
@ -154,7 +155,7 @@ public void setAuthenticationMethod( String authenticationMethod )
this.authenticationMethod = authenticationMethod==null?"":authenticationMethod;
}
@Schema(description = "True, if the LDAP bind authentication is used for logging in to Archiva")
@Schema(name="bind_authenticator_enabled", description = "True, if the LDAP bind authentication is used for logging in to Archiva")
public boolean isBindAuthenticatorEnabled( )
{
return bindAuthenticatorEnabled;
@ -165,7 +166,7 @@ public void setBindAuthenticatorEnabled( boolean bindAuthenticatorEnabled )
this.bindAuthenticatorEnabled = bindAuthenticatorEnabled;
}
@Schema(description = "True, if the archiva role name is also the LDAP group name")
@Schema(name="user_role_name_as_group", description = "True, if the archiva role name is also the LDAP group name")
public boolean isUseRoleNameAsGroup( )
{
return useRoleNameAsGroup;
@ -246,16 +247,16 @@ public int hashCode( )
public String toString( )
{
final StringBuilder sb = new StringBuilder( "LdapConfiguration{" );
sb.append( "hostName='" ).append( hostName ).append( '\'' );
sb.append( "host_name='" ).append( hostName ).append( '\'' );
sb.append( ", port=" ).append( port );
sb.append( ", sslEnabled=" ).append( sslEnabled );
sb.append( ", baseDn='" ).append( baseDn ).append( '\'' );
sb.append( ", groupsBaseDn='" ).append( groupsBaseDn ).append( '\'' );
sb.append( ", bindDn='" ).append( bindDn ).append( '\'' );
sb.append( ", bindPassword='" ).append( bindPassword ).append( '\'' );
sb.append( ", authenticationMethod='" ).append( authenticationMethod ).append( '\'' );
sb.append( ", bindAuthenticatorEnabled=" ).append( bindAuthenticatorEnabled );
sb.append( ", useRoleNameAsGroup=" ).append( useRoleNameAsGroup );
sb.append( ", ssl_enabled=" ).append( sslEnabled );
sb.append( ", base_dn='" ).append( baseDn ).append( '\'' );
sb.append( ", groups_base_dn='" ).append( groupsBaseDn ).append( '\'' );
sb.append( ", bind_dn='" ).append( bindDn ).append( '\'' );
sb.append( ", bind_password='" ).append( bindPassword ).append( '\'' );
sb.append( ", authentication_method='" ).append( authenticationMethod ).append( '\'' );
sb.append( ", bind_authenticator_enabled=" ).append( bindAuthenticatorEnabled );
sb.append( ", use_role_name_as_group=" ).append( useRoleNameAsGroup );
sb.append( ", properties=" ).append( properties );
sb.append( ", writable=" ).append( writable );
sb.append( '}' );

View File

@ -30,6 +30,7 @@
* @author Martin Stockhammer <martin_s@apache.org>
*/
@XmlRootElement(name = "securityConfiguration")
@Schema(name = "SecurityConfiguration", description = "Security configuration attributes.")
public class SecurityConfiguration implements Serializable
{
private static final long serialVersionUID = -4186866365979053029L;
@ -55,7 +56,7 @@ public static SecurityConfiguration ofRedbackConfiguration( RedbackRuntimeConfig
return secConfig;
}
@Schema(description = "List of ids of the active user managers")
@Schema(name="active_user_managers", description = "List of ids of the active user managers")
public List<String> getActiveUserManagers( )
{
return activeUserManagers;
@ -71,7 +72,7 @@ public void addSelectedUserManager(String userManager) {
this.activeUserManagers.add( userManager );
}
@Schema(description = "List of ids of the active rbac managers")
@Schema(name="active_rbac_managers", description = "List of ids of the active rbac managers")
public List<String> getActiveRbacManagers( )
{
return activeRbacManagers;
@ -99,7 +100,7 @@ public void setProperties( Map<String, String> properties )
this.properties.putAll( properties );
}
@Schema(description = "True, if the user cache is active. It caches data from user backend.")
@Schema(name="user_cache_enabled", description = "True, if the user cache is active. It caches data from user backend.")
public boolean isUserCacheEnabled( )
{
return userCacheEnabled;
@ -110,7 +111,7 @@ public void setUserCacheEnabled( boolean userCacheEnabled )
this.userCacheEnabled = userCacheEnabled;
}
@Schema(description = "True, if LDAP is used as user manager")
@Schema(name="ldap_active", description = "True, if LDAP is used as user manager")
public boolean isLdapActive( )
{
return ldapActive;
@ -152,11 +153,11 @@ public int hashCode( )
public String toString( )
{
final StringBuilder sb = new StringBuilder( "SecurityConfiguration{" );
sb.append( "selectedUserManagers=" ).append( activeUserManagers );
sb.append( ", selectedRbacManagers=" ).append( activeRbacManagers );
sb.append( "active_user_managers=" ).append( activeUserManagers );
sb.append( ", active_rbac_managers=" ).append( activeRbacManagers );
sb.append( ", properties=" ).append( properties );
sb.append( ", userCacheEnabled=" ).append( userCacheEnabled );
sb.append( ", ldapActive=" ).append( ldapActive );
sb.append( ", user_cache_nabled=" ).append( userCacheEnabled );
sb.append( ", ldap_active=" ).append( ldapActive );
sb.append( '}' );
return sb.toString( );
}

View File

@ -53,7 +53,7 @@ public ArchivaRestError( ArchivaRestServiceException e )
}
}
@Schema(name="errorMessages", description = "The list of errors that occurred while processing the REST request")
@Schema(name="error_messages", description = "The list of errors that occurred while processing the REST request")
public List<ErrorMessage> getErrorMessages()
{
return errorMessages;

View File

@ -62,7 +62,7 @@ public static ErrorMessage of(String errorKey, String... args) {
return new ErrorMessage( errorKey, args );
}
@Schema(description = "The key of the error message. If this is empty, the message message must be set.")
@Schema(name="error_key", description = "The key of the error message. If this is empty, the message message must be set.")
public String getErrorKey()
{
return errorKey;

View File

@ -20,6 +20,7 @@
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.media.ArraySchema;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.parameters.RequestBody;
@ -75,10 +76,11 @@ public interface SecurityConfigurationService
},
responses = {
@ApiResponse( responseCode = "200",
description = "If the configuration could be retrieved"
description = "If the configuration could be retrieved",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = SecurityConfiguration.class))
),
@ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) )
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) )
}
)
SecurityConfiguration getConfiguration()
@ -99,9 +101,9 @@ SecurityConfiguration getConfiguration()
description = "If the configuration was updated"
),
@ApiResponse( responseCode = "422", description = "Invalid content data",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) ),
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) ),
@ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to update the configuration",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) )
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) )
}
)
Response updateConfiguration( SecurityConfiguration newConfiguration)
@ -131,7 +133,7 @@ Response updateConfiguration( SecurityConfiguration newConfiguration)
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = PagedResult.class))
),
@ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) )
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) )
}
)
PagedResult<PropertyEntry> getConfigurationProperties( @QueryParam("q") @DefaultValue( "" ) String searchTerm,
@ -151,16 +153,17 @@ PagedResult<PropertyEntry> getConfigurationProperties( @QueryParam("q") @Default
)
},
parameters = {
@Parameter(in = ParameterIn.PATH, name="propertyName", description = "The name of the property to update")
@Parameter(in = ParameterIn.PATH, name="propertyName", description = "The name of the property to get the value for")
},
responses = {
@ApiResponse( responseCode = "200",
description = "If the configuration could be retrieved"
description = "If the configuration could be retrieved",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = PropertyEntry.class))
),
@ApiResponse( responseCode = "404", description = "The given property name does not exist",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) ),
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) ),
@ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) )
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) )
}
)
PropertyEntry getConfigurationProperty( @PathParam ( "propertyName" ) String propertyName)
@ -185,11 +188,11 @@ PropertyEntry getConfigurationProperty( @PathParam ( "propertyName" ) String pr
description = "If the property value was updated."
),
@ApiResponse( responseCode = "400", description = "The body data is not valid",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) ),
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) ),
@ApiResponse( responseCode = "404", description = "The given property name does not exist",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) ),
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) ),
@ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) )
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) )
}
)
Response updateConfigurationProperty( @PathParam ( "propertyName" ) String propertyName, PropertyEntry propertyValue)
@ -208,10 +211,11 @@ Response updateConfigurationProperty( @PathParam ( "propertyName" ) String prop
},
responses = {
@ApiResponse( responseCode = "200",
description = "If the configuration could be retrieved"
description = "If the configuration could be retrieved",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = LdapConfiguration.class))
),
@ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) )
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) )
}
)
LdapConfiguration getLdapConfiguration( ) throws ArchivaRestServiceException;
@ -231,7 +235,7 @@ Response updateConfigurationProperty( @PathParam ( "propertyName" ) String prop
description = "If the configuration was updated"
),
@ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to update the information",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) )
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) )
}
)
Response updateLdapConfiguration( LdapConfiguration configuration ) throws ArchivaRestServiceException;
@ -248,10 +252,11 @@ Response updateConfigurationProperty( @PathParam ( "propertyName" ) String prop
},
responses = {
@ApiResponse( responseCode = "200",
description = "If the configuration could be retrieved"
description = "If the configuration could be retrieved",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = CacheConfiguration.class))
),
@ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) )
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) )
}
)
CacheConfiguration getCacheConfiguration( ) throws ArchivaRestServiceException;
@ -271,7 +276,7 @@ Response updateConfigurationProperty( @PathParam ( "propertyName" ) String prop
description = "If the configuration was updated"
),
@ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to update the information",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) )
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) )
}
)
Response updateCacheConfiguration( CacheConfiguration cacheConfiguration ) throws ArchivaRestServiceException;
@ -289,10 +294,12 @@ Response updateConfigurationProperty( @PathParam ( "propertyName" ) String prop
},
responses = {
@ApiResponse( responseCode = "200",
description = "If the list could be retrieved"
description = "If the list could be retrieved",
content = @Content(mediaType = APPLICATION_JSON, array = @ArraySchema(
schema = @Schema(implementation = BeanInformation.class)))
),
@ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) )
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) )
}
)
List<BeanInformation> getAvailableUserManagers()
@ -310,10 +317,12 @@ List<BeanInformation> getAvailableUserManagers()
},
responses = {
@ApiResponse( responseCode = "200",
description = "If the list could be retrieved"
description = "If the list could be retrieved",
content = @Content(mediaType = APPLICATION_JSON, array = @ArraySchema(
schema = @Schema(implementation = BeanInformation.class)))
),
@ApiResponse( responseCode = "403", description = "Authenticated user is not permitted to gather the information",
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestServiceException.class )) )
content = @Content(mediaType = APPLICATION_JSON, schema = @Schema(implementation = ArchivaRestError.class )) )
}
)
List<BeanInformation> getAvailableRbacManagers()