Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create API spec #993

Closed
jtojnar opened this issue Nov 2, 2017 · 1 comment
Closed

Create API spec #993

jtojnar opened this issue Nov 2, 2017 · 1 comment
Assignees
Labels
Milestone

Comments

@jtojnar
Copy link
Member

jtojnar commented Nov 2, 2017

We need machine readable API description. Among other things, it will allow us to check the implementation compliance automatically.

I tried to describe the API using OpenAPI 2 but it proved to be too limited. OpenAPI 3 looks more promising but the automated checking tooling does not seem to support it yet.

Depends on: apiaryio/dredd#894

@jtojnar jtojnar added the api label Nov 2, 2017
@jtojnar jtojnar added this to the 2.18 milestone Nov 2, 2017
@jtojnar jtojnar self-assigned this Nov 2, 2017
jtojnar added a commit that referenced this issue Jan 11, 2018
This patch adds the description of the RESTful API in OpenAPI 3.0 format.
Previously, the API was manually documented on the wiki without any guarantee
that the description matches reality. Formal description will allow us to
check for compliance automatically, as well as use other cool tools like Swagger UI.

Closes: #993
@jtojnar
Copy link
Member Author

jtojnar commented Jan 11, 2018

Bootprint might be more straightforward to set-up than Swagger UI but it also does not support OpenAPI 3.0.

--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
+/_docs/website/api
 /data/favicons/*.png
 /data/favicons/*.jpg
 /data/thumbnails/*.png
--- a/gruntfile.js
+++ b/gruntfile.js
@@ -163,11 +163,20 @@
         }
     });
 
+    grunt.registerTask('docs:api', 'API documentation', function() {
+        var bootprint = require('bootprint')
+           .load(require('bootprint-openapi'))
+           .build('docs/api-description.json','api')
+           .generate()
+           .done(console.log);
+    });
+
     grunt.registerTask('client:install', 'Install client-side dependencies.', ['auto_install']);
     grunt.registerTask('server:install', 'Install server-side dependencies.', ['composer:install:no-dev:optimize-autoloader:prefer-dist']);
     grunt.registerTask('install', 'Install both client-side and server-side dependencies.', ['client:install', 'server:install']);
     grunt.registerTask('default', ['install', 'versionupdater', 'compress']);
     grunt.registerTask('version', ['versionupdater']);
+    grunt.registerTask('docs', ['docs:api']);
     grunt.registerTask('zip', ['compress']);
     grunt.registerTask('lint:client', 'Check JS syntax', ['eslint']);
     grunt.registerTask('cs:server', 'Check PHP coding style', ['composer:run-script cs']);
--- a/package.json
+++ b/package.json
@@ -7,6 +7,8 @@
     "url": "https://github.com/SSilence/selfoss.git"
   },
   "devDependencies": {
+    "bootprint": "^1.0.2",
+    "bootprint-openapi": "^1.1.0",
     "grunt": "^0.4.5",
     "grunt-auto-install": "^0.3.1",
     "grunt-cli": "^1.2.0",

jtojnar added a commit that referenced this issue Jan 11, 2018
This patch adds the description of the RESTful API in OpenAPI 3.0 format.
Previously, the API was manually documented on the wiki without any guarantee
that the description matches reality. Formal description will allow us to
check for compliance automatically, as well as use other cool tools like Swagger UI.

Closes: #993
jtojnar added a commit that referenced this issue Mar 5, 2018
This patch adds the description of the RESTful API in OpenAPI 3.0 format.
Previously, the API was manually documented on the wiki without any guarantee
that the description matches reality. Formal description will allow us to
check for compliance automatically, as well as use other cool tools like Swagger UI.

Closes: #993
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

1 participant