fix: improve docs

Squashed commit of the following: commit a248ca022a68a20abce132222d29b439c8f9d1dc Author: Maximiliano Osorio <maxiosorio@gmail.com> Date: Fri Feb 28 10:21:53 2020 -0800 more docs commit 1d432835bb2126ebc3cf50a85d41b5da6f59146e Author: Maximiliano Osorio <maxiosorio@gmail.com> Date: Thu Feb 27 19:27:32 2020 -0800 more docs commit b6bc79d Author: Maximiliano Osorio <maxiosorio@gmail.com> Date: Thu Feb 27 19:16:44 2020 -0800 more docs commit d0898a6 Author: Maximiliano Osorio <maxiosorio@gmail.com> Date: Thu Feb 27 18:25:28 2020 -0800 more usability issues commit 4d20cfa Author: Maximiliano Osorio <maxiosorio@gmail.com> Date: Thu Feb 27 17:59:24 2020 -0800 fix: preview docs commit 6b4acc4 Author: Maximiliano Osorio <maxiosorio@gmail.com> Date: Thu Feb 27 17:58:57 2020 -0800 fix: usabilitiy issues
KnowledgeCaptureAndDiscovery · Feb 28, 2020 · 097f3fe · 097f3fe
1 parent 260da20
commit 097f3fe
Show file tree

Hide file tree

Showing 45 changed files with 346 additions and 147 deletions.
diff --git a/docs/advanced.md b/docs/advanced.md
diff --git a/docs/config.yaml.sample b/docs/config.yaml.sample
@@ -0,0 +1,20 @@
+ontologies:
+  - https://mintproject.github.io/Mint-ModelCatalog-Ontology/release/1.2.0/ontology.xml
+  - https://knowledgecaptureanddiscovery.github.io/SoftwareDescriptionOntology/release/1.4.0/ontology.xml
+name: modelcatalog
+output_dir: outputs
+
+openapi:
+  openapi: 3.0.1
+  info:
+    description: This is the API of the  Software Description Ontology
+      at [https://mintproject.github.io/Mint-ModelCatalog-Ontology/release/1.3.0/index-en.html](https://w3id.org/okn/o/sdm)
+    title: Model Catalog
+    version: v1.3.0
+  externalDocs:
+    description: Model Catalog
+    url: https://w3id.org/okn/o/sdm
+  servers:
+    - url: https://api.models.mint.isi.edu/v1.3.0
+    - url: https://dev.api.models.mint.isi.edu/v1.3.0
+    - url: http://localhost:8080/v1.3.0
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -15,7 +15,8 @@
 
 ## Running
 
-1. Create the OBA config file from the [sample configuration](../config.yaml.sample)
+
+1. Create the OBA config file from the [sample configuration](config.yaml.sample)
 2. Pass the configuration and run OBA
 ```bash
 $ java -jar oba-2.0.0-jar-with-dependencies.jar -c config.yaml

diff --git a/docs/server.md b/docs/server.md
@@ -0,0 +1,145 @@
+# Generating the server
+
+OBA uses [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator#overview) to generate the server.
+
+## OpenAPI Generator
+
+OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and 
+configuration automatically given an OpenAPI Spec (both 2.0 and 3.0 are supported). The OpenAPI Generator website
+maintains a list of languages/frameworks are supported.
+
+### Integration with RDF
+
+The OpenAPI Generator easily provide an API backend for mocking based on the OpenAPI Specification. However, it does not
+provide the logic of the server (For example, a database connection).
+
+OBA modifies the server generated by OpenAPI Generator using templates. As result, the server can:
+
+ 1. Connect and query resources from the SPARQL endpoint.
+    - Convert the RDF triples to JSON (using JSON/LD).
+ 2. Connect and insert resources to the SPARQL endpoint.
+    - Convert the JSON to RDF triples (using JSON/LD).
+
+## Generating the server
+
+Currently, the following languages/frameworks are supported by OBA:
+
+- Python/flash
+
+### How to generate it?
+
+!!! warning
+    You must install Docker.
+
+Run the script.
+
+```bash
+$ bash generate-server.sh
+...
+...
+SUCCESS
+```
+
+#### Structure of the server
+
+The server directory contains the following files and directories
+
+```bash
+$ ls server/
+Dockerfile: A Dockerfile to build the Docker Images
+README.md: A README.md with the instructions to run the server
+contexts: The directory with the JSON/LD contests
+openapi_server: The server implemenation
+queries: The directory with the SPARQL queries
+requirements.txt: The Python requirements of the server 
+test-requirements.txt: The Python requirements of testing the server 
+```
+
+
+### Generating the JSON/LD context
+
+Since the adoption of JSON/LD is in progress, OBA can convert the format of the responses from JSON/LD to JSON.
+To do that, OBA requires a file with the context. Simply speaking, a context is used to map terms to IRIs. 
+
+!!! info 
+    Visit the [JSON/LD documentation](https://json-ld.org/spec/latest/json-ld/#the-context) for more information
+
+Currently, OBA does not support the generation of the context file. 
+We recommend to use the project [owl2jsonld](https://github.com/stain/owl2jsonld)
+
+
+#### One ontology
+
+If you are using one only. You can run:
+
+```bash
+java -jar owl2jsonld-0.3.0-SNAPSHOT-standalone.jar  \
+    https://mintproject.github.io/Mint-ModelCatalog-Ontology/release/1.2.0/ontology.xml > server/context.json
+```
+
+### Two or more ontologies
+
+To merge the multiple JSON files, you can install the [jq](https://stedolan.github.io/jq/)
+
+```bash
+
+java -jar owl2jsonld-0.3.0-SNAPSHOT-standalone.jar  \
+    $ONTOLOGY_URL1 > a.json
+java -jar owl2jsonld-0.3.0-SNAPSHOT-standalone.jar \
+    $ONTOLOGY_URL2 > b.json    
+jq -s '.[0] * .[1]' a.json b.json  | jq -S > server/contexts/context.json
+rm a.json b.json
+
+```
+
+For example, the Model Catalog ontology:
+
+```bash
+
+java -jar owl2jsonld-0.3.0-SNAPSHOT-standalone.jar  \
+    https://mintproject.github.io/Mint-ModelCatalog-Ontology/release/1.2.0/ontology.xml > a.json
+java -jar owl2jsonld-0.3.0-SNAPSHOT-standalone.jar \
+    https://knowledgecaptureanddiscovery.github.io/SoftwareDescriptionOntology/release/1.2.0/ontology.xml > b.json
+jq -s '.[0] * .[1]' a.json b.json  | jq -S > server/contexts/context.json
+rm a.json b.json
+
+```
+
+## Running the server
+
+## Running with Docker
+
+To run the server on a Docker container, please execute the following from the root directory:
+
+```bash
+# building the image
+docker build -t openapi_server .
+
+# starting up a container
+docker run -p 8080:8080 openapi_server
+```
+
+
+and open your browser to here:
+!!! warning
+    The version (v1.3.0) depends of your configuration. If you have questions, go to the README.
+
+
+```
+http://localhost:8080/v1.3.0/ui/
+```
+
+Your OpenAPI definition lives here:
+
+```
+http://localhost:8080/v1.3.0/openapi.json
+```
+
+To launch the integration tests, use tox:
+```
+sudo pip install tox
+tox
+```
+
+## How to use it?
+
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -1,8 +1,9 @@
 site_name: OBA documentation
 nav:
   - Home: index.md
-  - Quickstart: quickstart.md
   - OBA features: features.md
+  - Quickstart: quickstart.md
+  - Generating the server: server.md
   - Configuration file: configuration_file.md
 theme:
   name: material

diff --git a/src/main/java/edu/isi/oba/DirectoryCopy.java b/src/main/java/edu/isi/oba/DirectoryCopy.java
diff --git a/src/main/java/edu/isi/oba/Mapper.java b/src/main/java/edu/isi/oba/Mapper.java
@@ -1,6 +1,5 @@
 package edu.isi.oba;
 
-import edu.isi.oba.config.OntologyConfig;
 import edu.isi.oba.config.RelationConfig;
 import edu.isi.oba.config.YamlConfig;
 import io.swagger.v3.oas.models.Paths;
@@ -11,9 +10,8 @@
 import org.semanticweb.owlapi.formats.RDFXMLDocumentFormat;
 import org.semanticweb.owlapi.model.*;
 import org.semanticweb.owlapi.rdf.rdfxml.renderer.OWLOntologyXMLNamespaceManager;
-import org.semanticweb.owlapi.util.DefaultPrefixManager;
 
-import java.io.IOException;
+import java.io.File;
 import java.util.*;
 
 class Mapper {
@@ -28,8 +26,8 @@ public Mapper(YamlConfig config_data) throws OWLOntologyCreationException {
     List<String> paths = config_data.getPaths();
 
     this.selected_paths = paths;
-    List<String>  config_ontologies = config_data.getOntologies();
-    Map<String, List<RelationConfig>> relations = config_data.getRelations();
+    List<String> config_ontologies = config_data.getOntologies();
+    String destination_dir = config_data.getOutput_dir() + File.separator + config_data.getName();
 
     //Load the ontology into the manager
     for (String ontologyURL : config_ontologies) {
@@ -47,7 +45,7 @@ public Mapper(YamlConfig config_data) throws OWLOntologyCreationException {
     //Add schema and paths
     for (OWLOntology ontology : this.manager.getOntologies()) {
       OWLDocumentFormat format = ontology.getFormat();
-      this.createSchemas(ontology, relations, format);
+      this.createSchemas(ontology, format, destination_dir);
     }
   }
 
@@ -56,16 +54,15 @@ public Mapper(YamlConfig config_data) throws OWLOntologyCreationException {
    * The schemas includes the properties
    *
    * @param ontology  Represents an OWL 2 ontology
-   * @param relations
    * @param format
    * @return schemas
    */
-  private void createSchemas(OWLOntology ontology, Map<String, List<RelationConfig>> relations, OWLDocumentFormat format) {
+  private void createSchemas(OWLOntology ontology, OWLDocumentFormat format, String destination_dir) {
     String defaultOntologyPrefixIRI = ((RDFXMLDocumentFormat) format).getDefaultPrefix();
 
     Set<OWLClass> classes = ontology.getClassesInSignature();
 
-    Query query = new Query();
+    Query query = new Query(destination_dir);
     Path pathGenerator = new Path();
     query.get_all(DEFAULT_DIR_QUERY);
 
@@ -82,14 +79,6 @@ private void createSchemas(OWLOntology ontology, Map<String, List<RelationConfig
           Schema schema = mapperSchema.getSchema();
           schemas.put(schema.getName(), schema);
 
-
-          //obtain the relations
-//          List<RelationConfig> model_relations = relations.get(mapperSchema.name);
-//          for (RelationConfig model_relation : model_relations){
-//              add_path_relation(pathGenerator, model_relation.getSubject(), model_relation.getPredicate(), model_relation.getPath());
-//          }
-
-
           if (this.selected_paths == null){
             add_path(pathGenerator, mapperSchema);
           } else {

diff --git a/src/main/java/edu/isi/oba/Oba.java b/src/main/java/edu/isi/oba/Oba.java
@@ -9,17 +9,19 @@
 import java.io.*;
 import java.net.URISyntaxException;
 import java.net.URL;
-import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.Paths;
-import java.nio.file.StandardCopyOption;
 import java.util.*;
+import java.util.logging.Level;
+import java.util.logging.Logger;
 
 import org.apache.commons.cli.*;
 
 class Oba {
+  private final static Logger LOGGER = Logger.getLogger(Oba.class.getName());
   public static void main(String[] args) throws Exception {
-    String resourcesFolder = "oba_python";
+    LOGGER.setLevel(Level.INFO);
+    String resources_server = "/servers.zip";
 
     //parse command line
     String config_yaml = get_config_yaml(args);
@@ -28,60 +30,25 @@ public static void main(String[] args) throws Exception {
     //copy base project
     String destination_dir = config_data.getOutput_dir() + File.separator + config_data.getName();
 
+
     //read ontologies and get schema and paths
 
     Mapper mapper = new Mapper(config_data);
     LinkedHashMap<String, PathItem> custom_paths = config_data.getCustom_paths();
     OpenAPI openapi_base = config_data.getOpenapi();
+    ObaUtils.unZipIt(resources_server, destination_dir);
     generate_openapi_spec(openapi_base, mapper, destination_dir, custom_paths);
-
     //python_copy_base_project(resourcesFolder, destination_dir);
   }
 
 
-  /**
-   * Copy the base project dir for a python project
-   * @param base_project_dir
-   * @param destination_dir
-   * @throws IOException
-   */
-  private static void python_copy_base_project(String base_project_dir, String destination_dir) throws IOException, URISyntaxException {
-    DirectoryCopy d = new DirectoryCopy();
-    InputStream originFolder = Oba.class.getResourceAsStream(base_project_dir);
-
-    ClassLoader loader = Thread.currentThread().getContextClassLoader();
-    URL url = loader.getResource("oba_python");
-    String path = url.getPath();
-    File[] a = new File(path).listFiles();
-    System.out.println(path);
-    //System.out.println(originFolder.getPath());
-    System.out.println(destination_dir);
-
-    d = new DirectoryCopy();
-    d.copyFolder(new File(path), new File(destination_dir));
-
-    System.out.println(destination_dir);
-
-
-
-
-  }
-
   private static void generate_openapi_spec(OpenAPI openapi_base, Mapper mapper, String dir, LinkedHashMap<String, PathItem> custom_paths) throws IOException {
-    String destinationProjectDirectory = dir;
+    String destinationProjectDirectory = dir + File.separator + "servers" + File.separator + "python";
     Path destinationProject = Paths.get(destinationProjectDirectory);
     Serializer serializer = new Serializer(mapper, destinationProject, openapi_base, custom_paths);
     SerializerPython serializer_python = new SerializerPython(mapper, destinationProject, openapi_base);
   }
 
-  private static File[] getResourceFolderFiles (String folder) {
-    ClassLoader loader = Thread.currentThread().getContextClassLoader();
-    URL url = loader.getResource(folder);
-    String path = url.getPath();
-    return new File(path).listFiles();
-  }
-
-
   private static YamlConfig get_yaml_data(String config_yaml) {
     Constructor constructor = new Constructor(YamlConfig.class);
     Yaml yaml = new Yaml(constructor);