oas-builder

Code your openapi specifications using a fluent interface that integrates seamlessly with fluent-json-schema.

Usage

The builder methods and factories follow the openapi specification relatively closely. You should be able to guess the corresponding factory function for a certain section of the spec.

Build your document

const OAS = require('@avanzu/oas-builder')
  
const document = OAS.document()
    .info(
        OAS.info().version('1.2.3')
    )
    .server(
        OAS.server()
            .url('https://dev.api.avanzu.de')
            .description('Development server')
    )
    .server(
        OAS.server()
            .url('https://api.avanzu.de')
            .description('Production Server')
    )
    .tag(
        OAS.tag()
            .name('Contacts')
            .description(
                'Vestibulum ante ipsum primis in faucibus orci luctus et ultrices', 
                'posuere cubilia Curae Curabitur luctus lacus eros. ',
                'Mauris tortor lacus, condimentum nec eleifend in, aliquet ut metus.', 
                'Sed varius tellus vitae nisi congue eu fringilla tellus aliquet.',
                'Nulla suscipit porttitor velit, id lobortis orci congue at.' 
            )
    )

module.exports = document    

Add Schemas

When it comes to schemas, you can use fluent-json-schema or plain old objects. You can even mix both styles as you see fit.

const OAS = require('@avanzu/oas-builder')
const S = requrie('fluent-json-schema')

const addSchemas = (document) => {

    const contact = S.object()
        .prop('name', S.string())
        .prop('email', S.string().format('email'))

    return document
        .schema('Contact', contact)
        .schema(
            'Phone', 
            { 
                type: 'object', 
                properties: { 
                    mobile: { type: 'string' } 
                } 
            }
        )
}

Add Paths

All builder methods do not change the internal state of that instance. Instead they will produce a new instance with the new internal state. You have to take that into account when you intend to stop and restart chaining.

This allows to branch off from a common base element without interference.

const OAS = require('@avanzu/oas-builder')
const S = requrie('fluent-json-schema')

const addPath = (document) => {

    const baseOp = OAS.op().tag('Contacts').BadRequest().GatewayTimeout()

    const listContacts = baseOp
        .id('listContacts')
        .Ok(
            OAS.body()
                .description('lists contacts')
                .json(OAS.content().schema(S.object()).example({}))
        )

    const addContact = baseOp
        .id('addContact')
        .request(
            OAS.body()
                .description('add contact payload')
                .json(OAS.content().schema(contactSchema))
        )
        .Created(
            OAS.body()
                .json(OAS.content().schema(OAS.ref().schema('Contact')))
                .description('added contact')
        )

    const getContact = baseOp
        .id('getContact')
        .idPath('id')
        .Ok(
            OAS.body()
                .json(OAS.content().schema(OAS.ref().schema('Contact')))
                .description('found contact')
        )
        .NotFound()

    return document
        .path('/contacts', OAS.path().get(listContacts).post(addContact))
        .path('/contacts/{id}', OAS.path().get(getContact))
}

Render your spec

In order to generate the JSON representation, you will have to call the valueOf method.

const openapiJSON = document.valueOf() 

Shorthands and quality of life features

The openapi specification can be somewhat cumbersome to write. Hence, most of the builders come with a few shorthands to improve the developer experience.

Descriptions

Since regular javascript strings cannot be written in multiple lines naturally and template strings will probably mess up your indentation, every description method accepts an arbitrarty amount of strings which will be joined with a line break \n. For an example, see the tag definition in build your document.

OAS.document()

The document builder provides shorthands for the components section of the openapi document section.

• schema(name, value) - Adds the given schema to the schemas field, using the given name as key.
• response(name, value) - Adds the given response to the responses field, using the given name as key.
• parameter(name, value) - adds the given parameter to the parameters field, using the given name as key.
• example(name, value) - adds the given example to the examples field, using the gven name as key.
• requestBody(name, value) - adds the given requestBody to the requestBodies field, using the gven name as key.
• header(name, value) - adds the given header to the headers field, using the gven name as key.
• securityScheme(name, value) - adds the given securityScheme to the securitySchemes field, using the gven name as key.

OAS.ref()

The reference builder provides shorthands into the components section of the openapi document.

• schema(name) - generates a reference to the given name in the schemas field
• response(name) - generates a reference to the given name in the responses field
• param(name) - generates a reference to the given name in the parameters field
• body(name) - generates a reference to the given name in the requestBodies field
• header(name) - generates a reference to the given name in the headers field
• security(name) - generates a reference to the given name in the securitySchemes field
• link(name) - generates a reference to the given name in the links field
• callback(name) - generates a reference to the given name in the callbacks field
• pathItem(name) - generates a reference to the given name in the pathItems field

OAS.op()

• idPath(name[, description[, type]]) - adds a required path parameter with the given name to the parameters of the operation.
• query(schema) - adds the properties of the given schema (plain or fluent) as query parameters to the operation.

Responses

For the most used response types in terms of status codes, there are individual methods with semantic names relating to the http status texts.

Success | Method | Body | Status code | Status text | | -------------- | -------- | ----------- | ------------- | | Ok | required | 200 | OK | | Created | required | 201 | Created | | Accepted | required | 202 | Accepted | | NoContent | required | 204 | No Content | | ResetContent | required | 205 | Reset Content |

Client errors

If you omit the response body, a default will be used with a description that is equal to the method name.

| Method | Body | Status code | Status text | | ------------------ | -------- | ----------- | ------------------ | | BadRequest | optional | 400 | Bad Request | | Unauthorized | optional | 401 | Unauthorized | | Forbidden | optional | 403 | Forbidden | | NotFound | optional | 404 | Not Found | | MethodNotAllowed | optional | 405 | Method Not Allowed | | NotAcceptable | optional | 406 | Not Acceptable | | RequestTimeout | optional | 408 | Request Timeout | | Conflict | optional | 409 | Conflict | | Unprocessable | optional | 422 | Unprocessable |

Server error

If you omit the response body, a default will be used with a description that is equal to the method name.

| Method | Body | Status code | Status text | | -------------------- | ------- | ----------- | ------------------- | | GeneralError | optonal | 500 | General Error | | NotImplemented | optonal | 501 | Not Implemented | | BadGateway | optonal | 502 | Bad Gateway | | ServiceUnavailable | optonal | 503 | Service Unavailable | | GatewayTimeout | optonal | 504 | Gateway Timeout |

OAS.body()

For the most used media types, there are also semantic methods available. | Method | Media type | | ------ | ------------------ | | json | application/json | | text | text/plain | | xml | application/xml | | any | */* |