Comment on page

Swagger specification

Swagger documentation can be divided into 2 sections:
REST API
Module specific controllers
How to use
The Swagger UI and the specification are served by the Swagger plugin.
Sending a request
Trying out the end points should be pretty straightforward. Each method is described, has a couple form elements that allow you to fill in request body and/or request parameters and at the bottom left you'll find a Try it out! button that will send the request to the server.
Specification of the REST API
The Molgenis REST API v1 and v2 are documented using the Swagger specification and you can browse the endpoints using the Swagger UI.
 This is a work in progress and not all endpoints are fully documented yet. 
Permissions
Admins can hand out plugin permissions on the Swagger plugin in the Permission Manager. Only users with view permission on the plugin can access the swagger specification. The specification uses enums for the entity_name parameter, and fills in the entities that the user can see.
URL
By default, the API documentation is added to the menu. If you remove it from the menu, users with plugin permissions can still access the plugin on the url <server>/plugin/swagger/.
Authorization
The Molgenis REST api supports two forms of authentication: The standard session token header and an x-molgenis-token header.
ApiKey
The Swagger 2 specification only supports ApiKey authorization. So the Molgenis Swagger plugin generates a Molgenis token and fills it in as the ApiKey in the Swagger UI. This token will then be added as an x-molgenis-token header by the Swagger UI to each request. You can view and edit the token by clicking the dark green Authorize button at the top of the page.
Api key authorization
Specification of module specific controllers
When you toggle the listbox in the header of the swagger documentation, you can choose different MOLGENIS-modules.
Swagger toggle modules
The workflow in swagger is pretty much the same as in the REST API documentation. Authentication does not work in this part of the MOLGENIS API documentation.
Contribute to module-API documentation
When you want to contribute to MOLGENIS and are developing a module, there are a few components that you have to configure.
Update module pom with swagger-maven-plugin:
<plugin>
  <groupId>com.github.kongchen</groupId>
  <artifactId>swagger-maven-plugin</artifactId>
  <configuration>
    <apiSources>
      <apiSource>
        <info>
          <title>${project.name}</title>
          <version>${project.version}</version>
          <description>${project.description}</description>
        </info>
        <springmvc>true</springmvc>
        <locations>
          <location>#location of controller#</location>
        </locations>
        <swaggerDirectory>${build.directory}/generated-resources/swagger</swaggerDirectory>
        <swaggerFileName>${project.name}-swagger</swaggerFileName>
      </apiSource>
    </apiSources>
  </configuration>
  <executions>
    <execution>
      <phase>compile</phase>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>
Add module to view-swagger-ui.ftl
urls: [
  { name: 'molgenis', url: '${molgenisUrl}' },
  { name: 'core-ui', url: '${baseUrl}/swagger/core-ui-swagger.json'}
  { name: '#module name from pom.xml#', url: '${baseUrl}/swagger/#module name from pom.xml#-swagger.json'}
],
Add swagger-annotations dependency to module pom.xml
<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-annotations</artifactId>
</dependency>
Do not specify a version. The version is maintained by the master-pom.
Add annotations to controller
@Api("Example API")
@Controller
@RequestMapping(URI)
public class ExamplePluginController extends PluginController
{
​
    @ApiOperation("Example operation")
    @ApiResponses({
            @ApiResponse(code = 200, message = "This is an example operation", response = String.class)
    })
    @GetMapping
    public String exampleOperation(@RequestParam(defaultValue = "false") boolean exmapleBoolean)
    {
For real life examples see the UserAccountController.java in MOLGENIS.

Interoperability

Data API

Last modified 3yr ago