cdmlib-remote-webapp/src/main/java/eu/etaxonomy/cdm/remote/config/CdmSwaggerConfig.disabled

   1 // $Id$
   2 /**
   3 * Copyright (C) 2014 EDIT
   4 * European Distributed Institute of Taxonomy
   5 * http://www.e-taxonomy.eu
   6 *
   7 * The contents of this file are subject to the Mozilla Public License Version 1.1
   8 * See LICENSE.TXT at the top of this package for the full license terms.
   9 */
  10 package eu.etaxonomy.cdm.remote.config;
  11
  12
  13 import java.util.Collection;
  14
  15 import javax.persistence.Entity;
  16
  17 import org.apache.log4j.Logger;
  18 import org.springframework.beans.factory.annotation.Autowired;
  19 import org.springframework.context.annotation.Bean;
  20 import org.springframework.context.annotation.Configuration;
  21 import org.springframework.core.type.filter.AnnotationTypeFilter;
  22
  23 import com.mangofactory.swagger.configuration.SpringSwaggerConfig;
  24 import com.mangofactory.swagger.plugin.SwaggerSpringMvcPlugin;
  25 import com.wordnik.swagger.model.ApiInfo;
  26
  27 import eu.etaxonomy.cdm.model.CdmAssignableTypeFilter;
  28 import eu.etaxonomy.cdm.model.CdmTypeScanner;
  29 import eu.etaxonomy.cdm.model.common.CdmBase;
  30
  31 /**
  32  * <h3>NOTE:</h3>
  33  *  For a detailed overview on the spring MVC and application context configuration and
  34  *  bootstrapping of this web application see:
  35  *  {@link http://dev.e-taxonomy.eu/trac/wiki/cdmlib-remote-webappConfigurationAndBootstrapping}
  36  *
  37  *
  38  */
  39 @Configuration
  40 public class CdmSwaggerConfig {
  41
  42     private static final String LSID_AUTHORITY_SERVICES = "LSID authority services";
  43
  44     private static final String DATA_EXPORT = "Data export";
  45
  46     private static final String GENERIC_REST_API = "Generic REST API";
  47
  48     private static final String WEB_PORTAL_SERVICES = "Web Portal Services";
  49
  50     private static final String CATALOGUE_SERVICES = "Catalogue Services";
  51
  52     public static final Logger logger = Logger.getLogger(CdmSwaggerConfig.class);
  53
  54     private SpringSwaggerConfig springSwaggerConfig;
  55
  56     Collection<Class<? extends Object>> allCdmTypes = null;
  57
  58     public CdmSwaggerConfig() {
  59         super();
  60         logger.debug("contructor");
  61
  62     }
  63
  64    /**
  65     * Required to autowire SpringSwaggerConfig
  66     */
  67    @Autowired
  68    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig) {
  69       this.springSwaggerConfig = springSwaggerConfig;
  70       logger.debug("setSpringSwaggerConfig");
  71    }
  72
  73    /**
  74     * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc framework - allowing for multiple
  75     * swagger groups i.e. same code base multiple swagger resource listings.
  76     */
  77 //   @Bean(name="swaggerPluginDefault")
  78    @Bean(name="swaggerPluginGenericAPI")
  79    public SwaggerSpringMvcPlugin swaggerPluginGenericAPI(){
  80        logger.debug("swaggerSpringMvcPlugin");
  81        configureModelConverters();
  82        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
  83           .apiInfo(apiInfo(GENERIC_REST_API, ""
  84                   + "<p>The CDM REST API is a RESTful interface to resources stored in the CDM."
  85                   + " The RESTful architecture allows accessing the various resources like Taxa, "
  86                   + "Names, References, Media, etc by stable URIs. Due to security constraints "
  87                   + "and to assure the integration of data, currently only read operations "
  88                   + "(= HTTP GET) are permitted, write operations may be available in the future.</p>"
  89                   + "<p>The architecture directly exposes domain model entities, i.e. it provides "
  90                   + "direct serializations of the objects as they are stored in the CDM but also "
  91                   + "returns TDOs of the CDM entities in some cases. The API Service provides an easy to use way "
  92                   + "to transfer CDM data to web based clients."
  93                   + "</p>"
  94                   + "<p>For more information like usage of this service please refer to "
  95                   + "<a href=\"http://cybertaxonomy.eu/cdmlib/rest-api.html\">http://cybertaxonomy.eu/cdmlib/rest-api.html</a>"))
  96           // below regex excludes the paths of all other groups,
  97           // !!! also hide the manage and progress controller
  98           .includePatterns("/(?!portal/)(?!taxon/oai)(?!reference/oai)(?!name_catalogue/)(?!authority/)(?!csv/)(?!checklist)(?!manage/)(?!progress/).*")
  99           .ignoredParameterTypes(allCdmTpyes())
 100           .swaggerGroup(GENERIC_REST_API)
 101 //          .excludeAnnotations(Deprecated.class) // TODO
 102           ;
 103    }
 104
 105    @Bean(name="swaggerPluginPortal")
 106    public SwaggerSpringMvcPlugin swaggerPluginPortal(){
 107        logger.debug("swaggerSpringMvcPlugin");
 108        configureModelConverters();
 109        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
 110           .apiInfo(apiInfo(WEB_PORTAL_SERVICES, "<p>The Portal Service is a specialization to the "
 111                   + "<a href=\"?group=Generic+REST+API\">Generic  REST API</a> as needed by CDM Dataportal "
 112                   + " that adds some fields like localized representations to the pure CDM entities. Another important difference "
 113                   + " is the initialization depth of the CDM entities. The Portal Service enpoints provide far bigger parts of the "
 114                   + " object graph.</p>"))
 115           .includePatterns("/portal/.*")
 116           .ignoredParameterTypes(allCdmTpyes())
 117           .swaggerGroup(WEB_PORTAL_SERVICES);
 118    }
 119
 120    @Bean(name="swaggerPluginNameCatalogue")
 121    public SwaggerSpringMvcPlugin swaggerPluginNameCatalogue(){
 122        configureModelConverters();
 123        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
 124            .apiInfo(apiInfo(
 125                    CATALOGUE_SERVICES,
 126                    "<p>These web services are optimized for using names taxonomic information and occurence data in workflow environments "
 127                    + " but are suitabale for all applicatoins in which fast response times are crucial."
 128                    + " Additional detailed documentation of these services can also be found at:</p>"
 129                    + "<ul>"
 130                    + "<li><a href=\"http://cybertaxonomy.eu/cdmlib/rest-api-name-catalogue.html\">Name Catalogue REST API</a>"
 131                    + "<li><a href=\"http://cybertaxonomy.eu/cdmlib/rest-api-occurrence-catalogue.html\">Occurrence Catalogue REST API</a>"
 132                    + "</ul>"
 133                    ))
 134            .includePatterns("/name_catalogue.*", "/occurrence_catalogue.*")
 135            .ignoredParameterTypes(allCdmTpyes())
 136            .swaggerGroup(CATALOGUE_SERVICES);
 137    }
 138
 139    @Bean(name="swaggerPluginOAIPMH")
 140    public SwaggerSpringMvcPlugin swaggerPluginOAIPMH(){
 141        logger.debug("swaggerSpringMvcPlugin");
 142        configureModelConverters();
 143        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
 144           .apiInfo(apiInfo(
 145                   "OAI-PMH",
 146                   "<p>This is an automatcially created documentation on the OAI-PMH service which is atually dedicated to REST services."
 147                   + " Since OAI-PMH is not a REST service in the original sense, you may want to refer to"
 148                   + " the more specific <a href=\"http://cybertaxonomy.eu/cdmlib/oai-pmh.html\">OAI-PMH documentation</a> or"
 149                   + " to the service endpoints them self, which also provide a good, comprehensive and selfexplanatory"
 150                   + " level of documentation:</p>"
 151                   + "<ul>"
 152                   + "<li><a href=\"../reference/oai?verb=Identify\">OAI-PMH for References</a></li>"
 153                   + "<li><a href=\"../taxon/oai?verb=Identify\">OAI-PMH for Taxa</a></li>"
 154                   + "</ul>"))
 155           .includePatterns("/reference/oai.*", "/taxon/oai.*")
 156           .ignoredParameterTypes(allCdmTpyes())
 157           .swaggerGroup("OAI-PMH");
 158    }
 159
 160    @Bean(name="swaggerPluginLSID")
 161    public SwaggerSpringMvcPlugin swaggerPluginLSID(){
 162        logger.debug("swaggerSpringMvcPlugin");
 163        configureModelConverters();
 164        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
 165           .apiInfo(apiInfo(LSID_AUTHORITY_SERVICES, ""))
 166           .includePatterns("/authority/.*")
 167           .ignoredParameterTypes(allCdmTpyes())
 168           .swaggerGroup(LSID_AUTHORITY_SERVICES);
 169    }
 170
 171    @Bean(name="swaggerPluginDataExport")
 172    public SwaggerSpringMvcPlugin swaggerPluginDataExport(){
 173        logger.debug("swaggerSpringMvcPlugin");
 174        configureModelConverters();
 175        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
 176           .apiInfo(apiInfo(DATA_EXPORT, ""))
 177           .includePatterns("/csv/.*", "/checklist.*")
 178           .ignoredParameterTypes(allCdmTpyes())
 179           .swaggerGroup(DATA_EXPORT);
 180    }
 181
 182
 183    /**
 184      *
 185      */
 186     private void configureModelConverters() {
 187         // fully skip the creation of cdm model documentation
 188         // since it will be too excessive to scan the huge cdm model
 189         // which in fact has cycles.
 190         // not sure if this is working !!!
 191 //       String emptyJSON = "{}";
 192 //       OverrideConverter sessionConverter = new OverrideConverter();
 193 //       sessionConverter.add(Session.class.getName(), emptyJSON);
 194 //       ModelConverters.addConverter(sessionConverter, true);
 195     }
 196
 197
 198        //TODO failes to convert json to model
 199        // "org.json4s.package$MappingException: Did not find value
 200        //            which can be converted into java.lang.String"
 201
 202
 203     /**
 204      * @return
 205      */
 206     private Class<Class<? extends Object>>[] allCdmTpyes() {
 207         if (allCdmTypes == null) {
 208             allCdmTypes = allCdmTypes();
 209             allCdmTypes.add(eu.etaxonomy.cdm.api.service.pager.Pager.class);
 210             allCdmTypes.add(eu.etaxonomy.cdm.api.facade.DerivedUnitFacade.class);
 211         }
 212         return allCdmTypes.toArray(new Class[allCdmTypes.size()]);
 213     }
 214
 215 /**
 216  * @return
 217  */
 218 private Collection<Class<? extends Object>> allCdmTypes() {
 219     boolean includeAbstract = true;
 220     boolean includeInterfaces = false;
 221     Collection<Class<? extends Object>> classes = null;
 222
 223     CdmTypeScanner<Object> scanner = new CdmTypeScanner<Object>(includeAbstract, includeInterfaces);
 224     scanner.addIncludeFilter(new AnnotationTypeFilter(Entity.class));
 225     scanner.addIncludeFilter(new CdmAssignableTypeFilter(CdmBase.class, includeAbstract, includeInterfaces));
 226     classes = scanner.scanTypesIn("eu/etaxonomy/cdm/model");
 227
 228     return classes;
 229 }
 230
 231    private ApiInfo apiInfo(String title, String description) {
 232        ApiInfo apiInfo = new ApiInfo(
 233                title,
 234                description,
 235                null, // terms of service
 236                "EditSupport@bgbm.org",
 237                "Mozilla Public License 2.0",
 238                "http://www.mozilla.org/MPL/2.0/"
 239          );
 240        return apiInfo;
 241      }
 242
 243
 244 }