Integrate API Documentation

2020-04-24 16:56:16 +02:00 · 2020-04-24 16:56:16 +02:00 · df9525095e
parent f4bca12ab7
commit df9525095e
13 changed files with 11163 additions and 11 deletions
--- a/8
+++ b/8
@ -1183,3 +1183,11 @@ e2e_cert:
 		-reqexts SAN \
 		-extensions SAN \
 		-config e2e-tests/openssl.cnf
+
+api_doc: doc/sources/manager-api/openapi-spec.yaml doc/sources/manager-api/config-codegen.json
+	@if [ -f "$(SWAGGER_CODEGEN)" ] ; then \
+	java -jar "$(SWAGGER_CODEGEN)" generate -i doc/sources/manager-api/openapi-spec.yaml -l html2 -o doc/pages/manager-api/ -c doc/sources/manager-api/config-codegen.json; \
+	else \
+		echo "Please run me with SWAGGER_CODEGEN=/path/to/swagger-codegen.jar"; \
+	fi
+
--- a/_example/etc/api-apache2.4.conf
+++ b/_example/etc/api-apache2.4.conf
@ -40,6 +40,7 @@
    # RewriteCond "%{REQUEST_URI}" "!\.html(?:/.*)?$"

    # REST URLs
+    RewriteCond "%{REQUEST_URI}" "!^/(?:doc)"
    RewriteRule "^/(.+)$" "/api.fcgi/$1" [PT]

    # 2) FastCGI engine
@ -83,6 +84,15 @@
        </IfModule>
    </Location>

+    # On-line documentation
+    Alias /doc/ __DEFDOCDIR__
+    <Directory __DEFDOCDIR__>
+        Require all granted
+        ErrorDocument 404 /notfound.html
+        Options +FollowSymLinks
+        DirectoryIndex index.html start.html
+    </Directory>
+
    # Uncomment this if site if you use SSL only
    #Header set Strict-Transport-Security "max-age=15768000"
 </VirtualHost>
--- a/_example/etc/api-apache2.X.conf
+++ b/_example/etc/api-apache2.X.conf
@ -40,6 +40,7 @@
    # RewriteCond "%{REQUEST_URI}" "!\.html(?:/.*)?$"

    # REST URLs
+    RewriteCond "%{REQUEST_URI}" "!^/(?:doc)"
    RewriteRule "^/(.+)$" "/api.fcgi/$1" [PT]

    # 2) FastCGI engine
@ -90,6 +91,21 @@
        </IfModule>
    </Location>

+    # On-line documentation
+    Alias /doc/ __DEFDOCDIR__
+    <Directory __DEFDOCDIR__>
+        <IfVersion >= 2.3>
+            Require all granted
+        </IfVersion>
+        <IfVersion < 2.3>
+            Order Deny,Allow
+            Allow from all
+        </IfVersion>
+        ErrorDocument 404 /notfound.html
+        Options +FollowSymLinks
+        DirectoryIndex index.html start.html
+    </Directory>
+
    # Uncomment this if site if you use SSL only
    #Header set Strict-Transport-Security "max-age=15768000"
 </VirtualHost>
--- a/_example/etc/api-apache2.conf
+++ b/_example/etc/api-apache2.conf
@ -40,6 +40,7 @@
    # RewriteCond "%{REQUEST_URI}" "!\.html(?:/.*)?$"

    # REST URLs
+    RewriteCond "%{REQUEST_URI}" "!^/(?:doc)"
    RewriteRule "^/(.+)$" "/api.fcgi/$1" [PT]

    # 2) FastCGI engine
@ -84,6 +85,16 @@
        </IfModule>
    </Location>

+    # On-line documentation
+    Alias /doc/ __DEFDOCDIR__
+    <Directory __DEFDOCDIR__>
+        Order allow,deny
+        Allow from all
+        ErrorDocument 404 /notfound.html
+        Options +FollowSymLinks
+        DirectoryIndex index.html start.html
+    </Directory>
+
    # Uncomment this if site if you use SSL only
    #Header set Strict-Transport-Security "max-age=15768000"
 </VirtualHost>
--- a/_example/etc/api-nginx.conf
+++ b/_example/etc/api-nginx.conf
@ -15,7 +15,13 @@ server {
  #set_real_ip_from  127.0.0.1;
  #real_ip_header    X-Forwarded-For;

-  rewrite ^/(.*)$ /api.psgi/$1 break;
+  location /doc/ {
+      alias /usr/share/doc/lemonldap-ng-doc/;
+      index index.html start.html;
+  }
+  location / {
+      rewrite ^/(.*)$ /api.psgi/$1;
+  }

  location ~ ^(?<sc>/.*\.psgi)(?:$|/) {

@ -37,17 +43,18 @@ server {
    # Uncomment this if you use https only
    #add_header Strict-Transport-Security "max-age=15768000";

-    # By default, access to this VHost is denied
-    # If you want to enable the manager APIs, you MUST
-    # implement a robust authentication scheme to protect this
-    # VHost since LemonLDAP::NG provides no protection to the
-    # Manager APIs yet
-    #
-    #allow 127.0.0.0/8;
-    #allow ::1/128;
-    deny all;
  }

+  # By default, access to this VHost is denied
+  # If you want to enable the manager APIs, you MUST
+  # implement a robust authentication scheme to protect this
+  # VHost since LemonLDAP::NG provides no protection to the
+  # Manager APIs yet
+  #
+  #allow 127.0.0.0/8;
+  #allow ::1/128;
+  deny all;
+
  # DEBIAN
  # If install was made with USEDEBIANLIBS (official releases), uncomment this
  #location /javascript/ {
--- a/doc/index.html
+++ b/doc/index.html
@ -5,9 +5,14 @@
 </head>
 <body>
    <div class="container text-center">
-        <h1>LemonLDAP::NG offline documentation</h1>
+        <h1>LemonLDAP::NG Administrator documentation</h1>
        <hr />
        <a href="pages/documentation/current/start.html" class="btn btn-lg btn-primary">Documentation</a>
    </div>
+    <div class="container text-center">
+        <h1>LemonLDAP::NG Manager API documentation</h1>
+        <hr />
+        <a href="pages/manager-api/index.html" class="btn btn-lg btn-primary">API Reference</a>
+    </div>
 </body>
 </html>
--- a/doc/pages/manager-api/.swagger-codegen-ignore
+++ b/doc/pages/manager-api/.swagger-codegen-ignore
@ -0,0 +1,23 @@
+# Swagger Codegen Ignore
+# Generated by swagger-codegen https://github.com/swagger-api/swagger-codegen
+
+# Use this file to prevent files from being overwritten by the generator.
+# The patterns follow closely to .gitignore or .dockerignore.
+
+# As an example, the C# client generator defines ApiClient.cs.
+# You can make changes and tell Swagger Codgen to ignore just this file by uncommenting the following line:
+#ApiClient.cs
+
+# You can match any string of characters against a directory, file or extension with a single asterisk (*):
+#foo/*/qux
+# The above matches foo/bar/qux and foo/baz/qux, but not foo/bar/baz/qux
+
+# You can recursively match patterns against a directory, file or extension with a double asterisk (**):
+#foo/**/qux
+# This matches foo/bar/qux, foo/baz/qux, and foo/bar/baz/qux
+
+# You can also negate patterns with an exclamation (!).
+# For example, you can ignore all files in a docs folder with the file extension .md:
+#docs/*.md
+# Then explicitly reverse the ignore rule for a single file:
+#!docs/README.md
--- a/doc/pages/manager-api/.swagger-codegen/VERSION
+++ b/doc/pages/manager-api/.swagger-codegen/VERSION
@ -0,0 +1 @@
+3.0.18
--- a/doc/pages/manager-api/index.html
+++ b/doc/pages/manager-api/index.html
--- a/doc/sources/manager-api/config-codegen.json
+++ b/doc/sources/manager-api/config-codegen.json
@ -0,0 +1,6 @@
+{ "appName": "LemonLDAP::NG",
+  "appDescription": "API documentation for the LemonLDAP::NG Manager API",
+  "infoUrl": "https://lemonldap-ng.org/",
+  "infoEmail": ""
+}
+
--- a/doc/sources/manager-api/openapi-spec.yaml
+++ b/doc/sources/manager-api/openapi-spec.yaml
@ -0,0 +1,785 @@
+openapi: 3.0.1
+info:
+  title: LemonLDAP::NG Manager API
+  description: The Manager API allows an administrator to modify the LemonLDAP::NG configuration programmatically. It is not meant to be accessed by end users.
+  version: 2.0.8
+servers:
+  - url: /api/v1
+tags:
+- name: samlsp
+  description: SAML Service Providers
+- name: oidcrp
+  description: OpenID Connect Relaying Parties
+- name: 2fa
+  description: Registered Second Factors
+  
+paths:
+  /api/v1/providers/saml/sp:
+    post:
+      tags:
+      - samlsp
+      summary: Create a new SAML Service provider
+      operationId: addsamlsp
+      requestBody:
+        description: SAML Service provider to add
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SamlSp'
+        required: true
+      responses:
+        201:
+          $ref: '#/components/responses/Created'
+        400:
+          $ref: '#/components/responses/Error'  
+        409:
+          $ref: '#/components/responses/Conflict'
+          
+  /api/v1/providers/saml/sp/findByConfKey:
+    get:
+      tags:
+      - samlsp
+      summary: Finds SAML Service providers by configuration key
+      description: Takes a search pattern to be tested against existing service providers
+      operationId: findSamlSpByConfKey
+      parameters:
+      - name: pattern
+        in: query
+        description: Search pattern
+        required: true
+        schema:
+          type: "string"
+        examples:
+          any: 
+            summary: Any value
+            value: "*"
+          prefix: 
+            summary: Given prefix
+            value: "zone1-*"
+          anywhere:
+            summary: Substring
+            value: "something"
+      responses:
+        200:
+          $ref: '#/components/responses/ManySamlSp'
+        400:
+          $ref: '#/components/responses/Error'  
+
+  /api/v1/providers/saml/sp/findByEntityId:
+    get:
+      tags:
+      - samlsp
+      summary: Finds SAML Service Provider by Entity ID
+      operationId: findSamlSpByEntityId
+      parameters:
+      - name: entityId
+        in: query
+        description: Entity ID to search
+        required: true
+        schema:
+          type: "string"
+        example: http://mysp.example.com/saml/metadata
+      responses:
+        200:
+          $ref: '#/components/responses/OneSamlSp'
+        400:
+          $ref: '#/components/responses/Error'  
+        404:
+          $ref: '#/components/responses/NotFound'
+          
+  /api/v1/providers/saml/sp/{confKey}:
+    get:
+      tags:
+      - samlsp
+      summary: Get SAML Service Provider by configuration key
+      description: Returns a single Service Provider
+      operationId: getSamlSpByConfKey
+      parameters:
+      - name: confKey
+        in: path
+        description: Configuration key of SAML Service Provider
+        required: true
+        schema:
+          $ref: '#/components/schemas/confKey'
+      responses:
+        200:
+          $ref: '#/components/responses/OneSamlSp'
+        400:
+          $ref: '#/components/responses/Error'  
+        404:
+          $ref: '#/components/responses/NotFound'
+
+    put:
+      tags:
+      - samlsp
+      summary: Replaces a SAML Service
+      operationId: replaceSamlSp
+      parameters:
+      - name: confKey
+        in: path
+        description: Configuration key of SAML Service Provider that needs to be replaced
+        required: true
+        schema:
+          $ref: '#/components/schemas/confKey'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SamlSp'
+      responses:
+        204:
+          $ref: '#/components/responses/NoContent'
+        400:
+          $ref: '#/components/responses/Error'     
+        404:
+          $ref: '#/components/responses/NotFound'
+        409:
+          $ref: '#/components/responses/Conflict'
+    patch:
+      tags:
+      - samlsp
+      summary: Updates a SAML Service.
+      operationId: updateSamlSp
+      parameters:
+      - name: confKey
+        in: path
+        description: Configuration key of SAML Service Provider that needs to be updated
+        required: true
+        schema:
+          $ref: '#/components/schemas/confKey'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SamlSpUpdate'
+      responses:
+        204:
+          $ref: '#/components/responses/NoContent'
+        400:
+          $ref: '#/components/responses/Error'
+        404:
+          $ref: '#/components/responses/NotFound'
+        409:
+          $ref: '#/components/responses/Conflict'
+          
+    delete:
+      tags:
+      - samlsp
+      summary: Deletes a SAML Service Provider
+      operationId: deleteSamlSp
+      parameters:
+      - name: confKey
+        in: path
+        description: Configuration key of SAML Service Provider to delete
+        required: true
+        schema:
+          $ref: '#/components/schemas/confKey'
+      responses:
+        204:
+          $ref: '#/components/responses/NoContent'
+        400:
+          $ref: '#/components/responses/Error'  
+        404:
+          $ref: '#/components/responses/NotFound'     
+   
+  /api/v1/providers/oidc/rp:
+    post:
+      tags:
+      - oidcrp
+      summary: Create a new OpenID Connect Relaying Party
+      operationId: addoidcrp
+      requestBody:
+        description: OpenID Connect Relaying Party to add
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OidcRp'
+        required: true
+      responses:
+        201:
+          $ref: '#/components/responses/Created'
+        400:
+          $ref: '#/components/responses/Error'
+        409:
+          $ref: '#/components/responses/Conflict'
+  /api/v1/providers/oidc/rp/findByConfKey:
+    get:
+      tags:
+      - oidcrp
+      summary: Finds OpenID Connect Relaying Partys by configuration key
+      description: Takes a search pattern to be tested against existing service providers
+      operationId: findOidcRpByConfKey
+      parameters:
+      - name: pattern
+        in: query
+        description: Search pattern
+        required: true
+        schema:
+          $ref: '#/components/schemas/confKey'
+        examples:
+          any: 
+            summary: Any value
+            value: "*"
+          prefix: 
+            summary: Given prefix
+            value: "zone1-*"
+          anywhere:
+            summary: Substring
+            value: "something"
+      responses:
+        200:
+          $ref: '#/components/responses/ManyOidcRp'
+        400:
+          $ref: '#/components/responses/Error'  
+
+  /api/v1/providers/oidc/rp/findByClientId:
+    get:
+      tags:
+      - oidcrp
+      summary: Finds OpenID Connect Relaying Party by Client ID
+      operationId: findOidcRpByClientId
+      parameters:
+      - name: clientId
+        in: query
+        description: Client ID to search
+        required: true
+        schema:
+          type: "string"
+        example: my_client_id
+      responses:
+        200:
+          $ref: '#/components/responses/OneOidcRp'
+        400:
+          $ref: '#/components/responses/Error'  
+        404:
+          $ref: '#/components/responses/NotFound'
+  /api/v1/providers/oidc/rp/{confKey}:
+    get:
+      tags:
+      - oidcrp
+      summary: Get OpenID Connect Relaying Party by configuration key
+      description: Returns a single Service Provider
+      operationId: getOidcRpByConfKey
+      parameters:
+      - name: confKey
+        in: path
+        description: Configuration key of OpenID Connect Relaying Party
+        required: true
+        schema:
+          $ref: '#/components/schemas/confKey'
+      responses:
+        200:
+          $ref: '#/components/responses/OneOidcRp'
+        400:
+          $ref: '#/components/responses/Error'  
+        404:
+          $ref: '#/components/responses/NotFound'
+
+    patch:
+      tags:
+      - oidcrp
+      summary: Updates an OpenID Connect Relaying Party
+      operationId: updateOidcRp
+      parameters:
+      - name: confKey
+        in: path
+        description: Configuration key of OpenID Connect Relaying Party that needs to be updated
+        required: true
+        schema:
+          $ref: '#/components/schemas/confKey'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OidcRpUpdate'
+      responses:
+        204:
+          $ref: '#/components/responses/NoContent'
+        400:
+          $ref: '#/components/responses/Error'    
+        404:
+          $ref: '#/components/responses/NotFound'
+        409:
+          $ref: '#/components/responses/Conflict'
+    put:
+      tags:
+      - oidcrp
+      summary: Replaces an OpenID Connect Relaying Party
+      operationId: replaceOidcRp
+      parameters:
+      - name: confKey
+        in: path
+        description: Configuration key of OpenID Connect Relaying Party that needs to be replaced
+        required: true
+        schema:
+          $ref: '#/components/schemas/confKey'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/OidcRp'
+      responses:
+        204:
+          $ref: '#/components/responses/NoContent'
+        400:
+          $ref: '#/components/responses/Error'
+        404:
+          $ref: '#/components/responses/NotFound'
+        409:
+          $ref: '#/components/responses/Conflict'
+
+    delete:
+      tags:
+      - oidcrp
+      summary: Deletes a OpenID Connect Relaying Party
+      operationId: deleteOidcRp
+      parameters:
+      - name: confKey
+        in: path
+        description: Configuration key of OpenID Connect Relaying Party to delete
+        required: true
+        schema:
+          $ref: '#/components/schemas/confKey'
+      responses:
+        204:
+          $ref: '#/components/responses/NoContent'
+        400:
+          $ref: '#/components/responses/Error'  
+        404:
+          $ref: '#/components/responses/NotFound'    
+ 
+  '/api/v1/secondFactor/{uid}':
+    description: Second factors for a particular user
+    parameters:
+      - name: uid
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      summary: List second factors for a user
+      description: ''
+      tags:
+      - 2fa
+      operationId: getSecondFactors
+      responses:
+        200:
+          $ref: '#/components/responses/SecondFactors'
+        404:
+          $ref: '#/components/responses/NotFound'
+          
+    delete:
+      summary: Delete all second factors for a user
+      description: ''
+      tags:
+      - 2fa
+      operationId: deleteSecondFactors
+      responses:
+        204:
+          $ref: '#/components/responses/NoContent'
+        404:
+          $ref: '#/components/responses/NotFound'
+
+          
+  '/api/v1/secondFactor/{uid}/type/{type}':
+    description: Second factors of a given type for a particular user
+    parameters:
+      - name: uid
+        in: path
+        required: true
+        schema:
+          type: string
+      - name: type
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      summary: List second factors for a user given its type
+      description: ''
+      tags:
+      - 2fa
+      operationId: getSecondFactorsByType
+      responses:
+        200:
+          $ref: '#/components/responses/SecondFactors'
+        404:
+          $ref: '#/components/responses/NotFound'
+          
+          
+    delete:
+      summary: Delete all second factors of a given type for a user 
+      description: ''
+      tags:
+      - 2fa
+      operationId: deleteSecondFactorsByType
+      responses:
+        204:
+          $ref: '#/components/responses/NoContent'
+        404:
+          $ref: '#/components/responses/NotFound'
+
+          
+  '/api/v1/secondFactor/{uid}/id/{id}':
+    description: Second factors of a given id for a particular user
+    parameters:
+      - name: uid
+        in: path
+        required: true
+        schema:
+          type: string
+      - name: id
+        in: path
+        required: true
+        schema:
+          type: string
+    get:
+      summary: Get second factors for a user given its ID
+      description: ''
+      tags:
+      - 2fa
+      operationId: getSecondFactorsById
+      responses:
+        200:
+          $ref: '#/components/responses/SecondFactors'
+        404:
+          $ref: '#/components/responses/NotFound'
+
+          
+    delete:
+      summary: Delete a second factors for a user 
+      description: ''
+      tags:
+      - 2fa
+      operationId: deleteSecondFactorsById
+      responses:
+        204:
+          $ref: '#/components/responses/NoContent'
+        404:
+          $ref: '#/components/responses/NotFound'
+
+
+components:
+  schemas:
+    confKey:
+      type: string
+      pattern: '^\w[\w\.\-]*$'
+    Error:
+      type: object
+      properties:
+        error:
+          type: string
+      required:
+        - error
+    SamlSp:
+      required:
+      - confKey
+      - metadata
+      type: object
+      properties:
+        confKey:
+          $ref: '#/components/schemas/confKey'
+        metadata:
+          type: string
+          example: '<?xml version="1.0"?><EntityDescriptor...'
+        exportedAttributes:
+          type: object
+          items:
+            $ref: '#/components/schemas/samlAttribute'
+        macros:
+          type: object
+          example:
+            myMacroName: "$macro(rule)"
+          
+        options:
+          $ref: '#/components/schemas/samlOptions'
+    SamlSpUpdate:
+      type: object
+      properties:
+        metadata:
+          type: string
+          
+          example: '<?xml version="1.0"?><EntityDescriptor...'
+        macros:
+          type: object
+          example:
+            myMacroName: "$macro(rule)"
+        exportedAttributes:
+          type: object
+          items:
+            $ref: '#/components/schemas/samlAttribute'
+        options:
+          $ref: '#/components/schemas/samlOptions'
+    samlOptions:
+      type: object
+      properties:
+        checkSSOMessageSignature:
+          type: boolean
+          default: 1
+        sessionNotOnOrAfterTimeout:
+          type: integer
+          default: 72000
+        signSLOMessage:
+          type: integer
+          minimum: -1
+          maximum: 1
+          default: -1
+        enableIDPInitiatedURL:
+          type: boolean
+        oneTimeUse:
+          type: boolean
+        checkSLOMessageSignature:
+          type: boolean
+          default: 1
+        encryptionMode:
+          type: string
+          enum: 
+              - none
+              - nameid
+              - assertion
+          default: none
+        notOnOrAfterTimeout:
+          type: integer
+          default: 72000
+        rule:
+          type: string
+        forceUTF8:
+          type: boolean
+          default: 1
+        signSSOMessage:
+          type: integer
+          minimum: -1
+          maximum: 1
+          default: -1
+        nameIDSessionKey:
+          type: string
+        nameIDFormat:
+          type: string
+          enum: 
+              - unspecified
+              - email
+              - x509
+              - windows
+              - kerberos
+              - entity
+              - persistent
+              - transient
+              - encrypted
+
+    samlAttribute:
+      type: object
+      properties:
+        mandatory:
+          type: boolean
+        friendlyName:
+          type: string
+        format:
+          type: string
+          example: 'urn:oasis:names:tc:SAML:2.0:attrname-format:basic'
+    OidcRp:
+      required:
+      - confKey
+      - clientId
+      - redirectUris
+      type: object
+      properties:
+        confKey:
+          $ref: '#/components/schemas/confKey'
+        clientId:
+          type: string
+        redirectUris:
+          type: array
+          items:
+            type: string
+            minItems: 1
+            format: "uri"
+        exportedVars:
+          type: object
+          example:
+            email: mail
+            family_name: sn
+            name: cn
+        extraClaims:
+          type: object
+          example:
+            myscope: "myattr1 myattr2 myattr3"
+        macros:
+          type: object
+          example:
+            myMacroName: "$macro(rule)"
+        options:
+          $ref: '#/components/schemas/OidcOptions'
+    OidcOptions:
+      type: object
+      properties:
+        logoutUrl:
+          type: string
+          format: url
+        clientSecret:
+          type: string
+          format: password
+        displayName:
+          type: string
+        allowOffline:
+          type: boolean
+        rule:
+          type: string
+        IDTokenSignAlg:
+          type: string
+          enum: 
+            - none
+            - HS256
+            - HS384
+            - HS512
+            - RS256
+            - RS384
+            - RS512
+          default: HS512
+        refreshToken:
+          type: boolean
+        public:
+          type: boolean
+        postLogoutRedirectUris:
+          type: string
+        logoutType:
+          type: string
+          enum: 
+            - front
+            - back
+          default: front
+        accessTokenExpiration:
+          type: integer
+        IDTokenForceClaims:
+          type: boolean
+        requirePKCE:
+          type: boolean
+        offlineSessionExpiration:
+          type: integer
+        redirectUris:
+          type: array
+          items:
+            type: string
+        bypassConsent:
+          type: boolean
+        logoutSessionRequired:
+          type: boolean
+        clientId:
+          type: string
+        IDTokenExpiration:
+          type: integer
+        authorizationCodeExpiration:
+          type: integer
+        icon:
+          type: string
+        userIDAttr:
+          type: string
+
+    OidcRpUpdate:
+      type: object
+      properties:
+        clientId:
+          type: string
+        exportedVars:
+          type: object
+          example:
+            email: mail
+            family_name: sn
+            name: cn
+        extraClaims:
+          type: object
+          example:
+            myscope: "myattr1 myattr2 myattr3"
+        macros:
+          type: object
+          example:
+            myMacroName: "$macro(rule)"
+        options:
+          $ref: '#/components/schemas/OidcOptions'
+          
+    SecondFactor:
+      type: object
+      required:
+        - type
+        - id
+      properties:
+        id:
+          type: string
+          description: "An opaque idenfifier for this particular token"
+        type:
+          type: string
+          description: "The type of token in use"
+          example: "TOTP, U2F, UBK (Yubikey)"
+        name:
+          type: string
+          description: "A user-set description of the token"
+    SecondFactors:
+      type: array
+      items:
+        $ref: "#/components/schemas/SecondFactor"
+
+
+  responses:
+    NoContent:
+      description: Successful modification
+    Created:
+      description: Successful creation
+    OneOidcRp:
+      description: Return an OpenID Connect Provider
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/OidcRp'
+    OneSamlSp:
+      description: Return a SAML Provider
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/SamlSp'
+    ManyOidcRp:
+      description: Return a list of OpenID Connect Providers
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '#/components/schemas/OidcRp'
+    ManySamlSp:
+      description: Return a list of SAML Providers
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '#/components/schemas/SamlSp'
+    NotFound:
+      description: The specified resource was not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Conflict:
+      description: The specified object could not be created because its configuration key, client_id or entityID already exists
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    Error:
+      description: An error was encountered when processing the request
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    SecondFactor:
+      description: Return a second factor
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/SecondFactor"
+    SecondFactors:
+      description: Return a list of second factors
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/SecondFactors"
+
+
--- a/lemonldap-ng-manager/MANIFEST
+++ b/lemonldap-ng-manager/MANIFEST
@ -210,6 +210,7 @@ site/htdocs/static/logos/zh.png
 site/htdocs/static/reverseTree.json
 site/htdocs/static/struct.json
 site/templates/2ndfa.tpl
+site/templates/api.tpl
 site/templates/diff.tpl
 site/templates/footer.tpl
 site/templates/header.tpl
--- a/lemonldap-ng-manager/site/templates/api.tpl
+++ b/lemonldap-ng-manager/site/templates/api.tpl
@ -0,0 +1,14 @@
+<html>
+<head>
+    <title>LemonLDAP::NG Manager API</title>
+    <link rel="stylesheet" type="text/css" href="/static/bwr/bootstrap/dist/css/bootstrap.min.css"/>
+</head>
+<body>
+    <div class="container text-center">
+        <h1>LemonLDAP::NG Manager API</h1>
+        <hr />
+        <a href="/doc/pages/manager-api/index.html" class="btn btn-lg btn-primary">API Reference</a>
+    </div>
+</body>
+</html>
+