001package org.hl7.fhir.r5.openapi;
002
003/*-
004 * #%L
005 * org.hl7.fhir.r5
006 * %%
007 * Copyright (C) 2014 - 2019 Health Level 7
008 * %%
009 * Licensed under the Apache License, Version 2.0 (the "License");
010 * you may not use this file except in compliance with the License.
011 * You may obtain a copy of the License at
012 * 
013 *      http://www.apache.org/licenses/LICENSE-2.0
014 * 
015 * Unless required by applicable law or agreed to in writing, software
016 * distributed under the License is distributed on an "AS IS" BASIS,
017 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
018 * See the License for the specific language governing permissions and
019 * limitations under the License.
020 * #L%
021 */
022
023import java.util.HashSet;
024import java.util.List;
025import java.util.Set;
026
027import org.hl7.fhir.r5.context.IWorkerContext;
028import org.hl7.fhir.r5.model.CapabilityStatement;
029import org.hl7.fhir.r5.model.CapabilityStatement.CapabilityStatementRestComponent;
030import org.hl7.fhir.r5.model.CapabilityStatement.CapabilityStatementRestResourceComponent;
031import org.hl7.fhir.r5.model.CapabilityStatement.CapabilityStatementRestResourceSearchParamComponent;
032import org.hl7.fhir.r5.model.CapabilityStatement.ResourceInteractionComponent;
033import org.hl7.fhir.r5.model.CapabilityStatement.ResourceVersionPolicy;
034import org.hl7.fhir.r5.model.Enumerations.RestfulCapabilityMode;
035import org.hl7.fhir.r5.model.CapabilityStatement.SystemInteractionComponent;
036import org.hl7.fhir.r5.model.CapabilityStatement.SystemRestfulInteraction;
037import org.hl7.fhir.r5.model.CapabilityStatement.TypeRestfulInteraction;
038import org.hl7.fhir.r5.model.CodeType;
039import org.hl7.fhir.r5.model.ContactDetail;
040import org.hl7.fhir.r5.model.ContactPoint;
041import org.hl7.fhir.r5.model.ContactPoint.ContactPointSystem;
042import org.hl7.fhir.r5.model.Enumerations.SearchParamType;
043import org.hl7.fhir.r5.model.SearchParameter;
044import org.hl7.fhir.r5.openapi.ParameterWriter.ParameterLocation;
045import org.hl7.fhir.r5.openapi.ParameterWriter.ParameterStyle;
046import org.hl7.fhir.r5.openapi.SchemaWriter.SchemaType;
047import org.hl7.fhir.utilities.Utilities;
048
049
050public class OpenApiGenerator {
051
052  private IWorkerContext context;
053  private CapabilityStatement source;
054  private Writer dest;
055
056  public OpenApiGenerator(IWorkerContext context, CapabilityStatement cs, Writer oa) {
057    this.context = context;
058    this.source = cs;
059    this.dest = oa;
060  }
061
062  public void generate(String license, String url) {
063    dest.info().title(source.present()).description(source.getDescription()).license(license, url).version(source.getVersion());
064    for (ContactDetail cd : source.getContact()) {
065      dest.info().contact(cd.getName(), email(cd.getTelecom()), url(cd.getTelecom()));
066    }
067    if (source.hasPublisher())
068      dest.info().contact(source.getPublisher(), null, null);
069
070    if (source.hasImplementation()) {
071      dest.server(source.getImplementation().getUrl()).description(source.getImplementation().getDescription());
072    }
073    dest.externalDocs().url(source.getUrl()).description("FHIR CapabilityStatement");
074
075    for (CapabilityStatementRestComponent csr : source.getRest()) {
076      if (csr.getMode() == RestfulCapabilityMode.SERVER) {
077        generatePaths(csr);
078      }
079    }
080    writeBaseParameters(dest.components());
081  }
082
083  private void writeBaseParameters(ComponentsWriter components) {
084    components.parameter("rid").name("rid").in(ParameterLocation.path).description("id of the resource (=Resource.id)").required(true).allowEmptyValue(false).style(ParameterStyle.simple)
085    .schema().type(SchemaType.string);
086    
087    components.parameter("hid").name("hid").in(ParameterLocation.path).description("id of the history entry (=Resource.meta.versionId)").required(true).allowEmptyValue(false).style(ParameterStyle.simple)
088    .schema().type(SchemaType.string);
089
090    components.parameter("summary").name("_summary").in(ParameterLocation.query).description("Requests the server to return a designated subset of the resource").allowEmptyValue().style(ParameterStyle.form)
091    .schema().type(SchemaType.string).enums("true", "text", "data", "count", "false");
092
093    components.parameter("format").name("_format").in(ParameterLocation.query).description("Specify alternative response formats by their MIME-types (when a client is unable acccess accept: header)").allowEmptyValue().style(ParameterStyle.form)
094    .schema().type(SchemaType.string).format("mime-type");
095
096    components.parameter("pretty").name("_pretty").in(ParameterLocation.query).description("Ask for a pretty printed response for human convenience").allowEmptyValue().style(ParameterStyle.form)
097    .schema().type(SchemaType.bool);
098
099    SchemaWriter p = components.parameter("elements").name("_elements").in(ParameterLocation.query).description("Requests the server to return a collection of elements from the resource").allowEmptyValue().style(ParameterStyle.form).explode(false)
100    .schema();
101    p.type(SchemaType.array).format("string");
102    p.items().format("string");
103
104    components.parameter("count").name("_count").in(ParameterLocation.query).description("The maximum number of search results on a page. The server is not bound to return the number requested, but cannot return more")
105    .schema().type(SchemaType.number);
106  }
107
108  private void generatePaths(CapabilityStatementRestComponent csr) {
109    generateMetadata();
110    for (CapabilityStatementRestResourceComponent r : csr.getResource())
111      generateResource(r);
112    if (hasOp(csr, SystemRestfulInteraction.HISTORYSYSTEM))
113      generateHistorySystem(csr);
114    if (hasOp(csr, SystemRestfulInteraction.SEARCHSYSTEM))
115      generateSearchSystem(csr);
116    if (hasOp(csr, SystemRestfulInteraction.BATCH) || hasOp(csr, SystemRestfulInteraction.TRANSACTION) )
117      generateBatchTransaction(csr);
118  }
119
120  private void generateResource(CapabilityStatementRestResourceComponent r) {
121    if (hasOp(r, TypeRestfulInteraction.SEARCHTYPE)) 
122      generateSearch(r);
123    if (hasOp(r, TypeRestfulInteraction.READ))
124      generateRead(r);
125    if (hasOp(r, TypeRestfulInteraction.CREATE)) 
126      generateCreate(r);
127    if (hasOp(r, TypeRestfulInteraction.UPDATE)) 
128      generateUpdate(r);
129    if (hasOp(r, TypeRestfulInteraction.PATCH)) 
130      generatePatch(r);
131    if (hasOp(r, TypeRestfulInteraction.DELETE)) 
132      generateDelete(r);
133    if (hasOp(r, TypeRestfulInteraction.HISTORYINSTANCE)) 
134      generateHistoryInstance(r);
135    if (hasOp(r, TypeRestfulInteraction.VREAD)) 
136      generateVRead(r);
137    if (hasOp(r, TypeRestfulInteraction.HISTORYTYPE)) 
138      generateHistoryType(r);
139  }
140
141  private void generateMetadata() {
142    OperationWriter op = makePathMetadata().operation("get");
143    op.summary("Return the server's capability statement");
144    op.operationId("metadata");
145    opOutcome(op.responses().defaultResponse());
146    ResponseObjectWriter resp = op.responses().httpResponse("200");
147    resp.description("the capbility statement");
148    if (isJson())
149      resp.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/CapabilityStatement");
150    if (isXml())
151      resp.content("application/fhir+xml").schemaRef(specRef()+"/CapabilityStatement.xsd");
152
153    // parameters - but do they apply?
154    op.paramRef("#/components/parameters/format");
155    op.paramRef("#/components/parameters/pretty");
156    op.paramRef("#/components/parameters/summary");
157    op.paramRef("#/components/parameters/elements");
158  }
159
160  private void generateRead(CapabilityStatementRestResourceComponent r) {
161    OperationWriter op = makePathResId(r).operation("get");
162    op.summary("Read the current state of the resource");
163    op.operationId("read"+r.getType());
164    opOutcome(op.responses().defaultResponse());
165    ResponseObjectWriter resp = op.responses().httpResponse("200");
166    resp.description("the resource being returned");
167    if (r.getVersioning() != ResourceVersionPolicy.NOVERSION)
168      resp.header("ETag").description("Version from Resource.meta.version as a weak ETag").schema().type(SchemaType.string);
169    if (isJson())
170      resp.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/"+r.getType());
171    if (isXml())
172      resp.content("application/fhir+xml").schemaRef(specRef()+"/"+r.getType()+".xsd");
173
174    // parameters:
175    op.paramRef("#/components/parameters/rid");
176    op.paramRef("#/components/parameters/summary");
177    op.paramRef("#/components/parameters/format");
178    op.paramRef("#/components/parameters/pretty");
179    op.paramRef("#/components/parameters/elements");
180  }
181
182  private void generateSearch(CapabilityStatementRestResourceComponent r) {
183    OperationWriter op = makePathResType(r).operation("get");
184    op.summary("Search all resources of type "+r.getType()+" based on a set of criteria");
185    op.operationId("search"+r.getType());
186    opOutcome(op.responses().defaultResponse());
187    ResponseObjectWriter resp = op.responses().httpResponse("200");
188    resp.description("the resource being returned");
189    if (isJson())
190      resp.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/Bundle");
191    if (isXml())
192      resp.content("application/fhir+xml").schemaRef(specRef()+"/Bundle.xsd");
193    // todo: how do we know that these apply? 
194    op.paramRef("#/components/parameters/format");
195    op.paramRef("#/components/parameters/pretty");
196    op.paramRef("#/components/parameters/summary");
197    op.paramRef("#/components/parameters/elements");
198    Set<String> set = new HashSet<>();
199    for (CapabilityStatementRestResourceSearchParamComponent spc : r.getSearchParam()) {
200      if (!set.contains(spc.getName())) {
201        set.add(spc.getName());
202        ParameterWriter p = op.parameter(spc.getName());
203        p.in(ParameterLocation.query).description(spc.getDocumentation());
204        p.schema().type(getSchemaType(spc.getType()));
205        if (spc.hasDefinition()) {
206          SearchParameter sp = context.fetchResource(SearchParameter.class, spc.getDefinition());
207          if (sp != null) {
208            p.description(sp.getDescription());
209          }
210        }
211      }
212    }
213  }
214
215  private void generateSearchSystem(CapabilityStatementRestComponent csr) {
216    OperationWriter op = makePathSystem().operation("get");
217    op.summary("Search all resources of all types based on a set of criteria");
218    op.operationId("searchAll");
219    opOutcome(op.responses().defaultResponse());
220    ResponseObjectWriter resp = op.responses().httpResponse("200");
221    resp.description("the resource being returned");
222    if (isJson())
223      resp.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/Bundle");
224    if (isXml())
225      resp.content("application/fhir+xml").schemaRef(specRef()+"/Bundle.xsd");
226    // todo: how do we know that these apply? 
227    op.paramRef("#/components/parameters/format");
228    op.paramRef("#/components/parameters/pretty");
229    op.paramRef("#/components/parameters/summary");
230    op.paramRef("#/components/parameters/elements");
231    Set<String> set = new HashSet<>();
232    set.add("_summary");
233    set.add("_format");
234    set.add("_pretty");
235    set.add("_elements");
236    for (CapabilityStatementRestResourceSearchParamComponent spc : csr.getSearchParam()) {
237      if (!set.contains(spc.getName())) {
238        set.add(spc.getName());
239        ParameterWriter p = op.parameter(spc.getName());
240        p.in(ParameterLocation.query).description(spc.getDocumentation());
241        p.schema().type(getSchemaType(spc.getType()));
242        if (spc.hasDefinition()) {
243          SearchParameter sp = context.fetchResource(SearchParameter.class, spc.getDefinition());
244          if (sp != null) {
245            p.description(sp.getDescription());
246          }
247        }
248      }
249    }
250  }
251
252  private SchemaType getSchemaType(SearchParamType type) {
253    switch (type) {
254    // case COMPOSITE:
255    case DATE: return SchemaType.dateTime;
256    case NUMBER: return SchemaType.number; 
257    case QUANTITY: return SchemaType.string;
258    case REFERENCE: return SchemaType.string;
259    case STRING: return SchemaType.string;
260    case TOKEN: return SchemaType.string;
261    case URI: return SchemaType.string;
262    }
263    return null;
264  }
265
266  private void generateHistoryType(CapabilityStatementRestResourceComponent r) {
267    OperationWriter op = makePathResHistListType(r).operation("get");
268    op.summary("Read the past states of the resource");
269    op.operationId("histtype"+r.getType());
270    opOutcome(op.responses().defaultResponse());
271    ResponseObjectWriter resp = op.responses().httpResponse("200");
272    resp.description("the resources being returned");
273    if (isJson())
274      resp.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/Bundle");
275    if (isXml())
276      resp.content("application/fhir+xml").schemaRef(specRef()+"/Bundle.xsd");
277    op.paramRef("#/components/parameters/summary");
278    op.paramRef("#/components/parameters/format");
279    op.paramRef("#/components/parameters/pretty");
280    op.paramRef("#/components/parameters/elements");
281    op.paramRef("#/components/parameters/count");
282
283    op.parameter("_since").in(ParameterLocation.query).description("Only include resource versions that were created at or after the given instant in time").schema().type(SchemaType.dateTime);
284    op.parameter("_at").in(ParameterLocation.query).description("Only include resource versions that were current at some point during the time period specified in the date time value (see Search notes on date searching)").schema().type(SchemaType.dateTime);
285    op.parameter("_list").in(ParameterLocation.query).description("Only include resource versions that are referenced in the specified list (current list references are allowed)").schema().type(SchemaType.string);
286  }
287
288  private void generateHistoryInstance(CapabilityStatementRestResourceComponent r) {
289    OperationWriter op = makePathResHistListId(r).operation("get");
290    op.summary("Read the past states of the resource");
291    op.operationId("histinst"+r.getType());
292    opOutcome(op.responses().defaultResponse());
293    ResponseObjectWriter resp = op.responses().httpResponse("200");
294    resp.description("the resources being returned");
295    if (isJson())
296      resp.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/Bundle");
297    if (isXml())
298      resp.content("application/fhir+xml").schemaRef(specRef()+"/Bundle.xsd");
299    op.paramRef("#/components/parameters/rid");
300    op.paramRef("#/components/parameters/summary");
301    op.paramRef("#/components/parameters/format");
302    op.paramRef("#/components/parameters/pretty");
303    op.paramRef("#/components/parameters/elements");
304    op.paramRef("#/components/parameters/count");
305
306    op.parameter("_since").in(ParameterLocation.query).description("Only include resource versions that were created at or after the given instant in time").schema().type(SchemaType.dateTime);
307    op.parameter("_at").in(ParameterLocation.query).description("Only include resource versions that were current at some point during the time period specified in the date time value (see Search notes on date searching)").schema().type(SchemaType.dateTime);
308    op.parameter("_list").in(ParameterLocation.query).description("Only include resource versions that are referenced in the specified list (current list references are allowed)").schema().type(SchemaType.string);
309  }
310
311  private void generateHistorySystem(CapabilityStatementRestComponent csr) {
312    OperationWriter op = makePathHistListSystem().operation("get");
313    op.summary("Read the past states of all resources");
314    op.operationId("histAll");
315    opOutcome(op.responses().defaultResponse());
316    ResponseObjectWriter resp = op.responses().httpResponse("200");
317    resp.description("the resources being returned");
318    if (isJson())
319      resp.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/Bundle");
320    if (isXml())
321      resp.content("application/fhir+xml").schemaRef(specRef()+"/Bundle.xsd");
322    op.paramRef("#/components/parameters/summary");
323    op.paramRef("#/components/parameters/format");
324    op.paramRef("#/components/parameters/pretty");
325    op.paramRef("#/components/parameters/elements");
326    op.paramRef("#/components/parameters/count");
327
328    op.parameter("_since").in(ParameterLocation.query).description("Only include resource versions that were created at or after the given instant in time").schema().type(SchemaType.dateTime);
329    op.parameter("_at").in(ParameterLocation.query).description("Only include resource versions that were current at some point during the time period specified in the date time value (see Search notes on date searching)").schema().type(SchemaType.dateTime);
330    op.parameter("_list").in(ParameterLocation.query).description("Only include resource versions that are referenced in the specified list (current list references are allowed)").schema().type(SchemaType.string);
331  }
332
333  private void generateVRead(CapabilityStatementRestResourceComponent r) {
334    OperationWriter op = makePathResHistId(r).operation("get");
335    op.summary("Read a past state of the resource");
336    op.operationId("vread"+r.getType());
337    opOutcome(op.responses().defaultResponse());
338    ResponseObjectWriter resp = op.responses().httpResponse("200");
339    resp.description("the resource being returned");
340    if (r.getVersioning() != ResourceVersionPolicy.NOVERSION)
341      resp.header("ETag").description("Version from Resource.meta.version as a weak ETag for that version").schema().type(SchemaType.string);
342    if (isJson())
343      resp.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/"+r.getType());
344    if (isXml())
345      resp.content("application/fhir+xml").schemaRef(specRef()+"/"+r.getType()+".xsd");
346    op.paramRef("#/components/parameters/rid");
347    op.paramRef("#/components/parameters/hid");
348    op.paramRef("#/components/parameters/summary");
349    op.paramRef("#/components/parameters/format");
350    op.paramRef("#/components/parameters/pretty");
351    op.paramRef("#/components/parameters/elements");
352  }
353
354  // todo: how does prefer header affect return type?
355  private void generateUpdate(CapabilityStatementRestResourceComponent r) {
356    OperationWriter op = makePathResId(r).operation("put");
357    if (r.getUpdateCreate())
358      op.summary("Update the current state of the resource (can create a new resource if it does not exist)");
359    else
360      op.summary("Update the current state of the resource");
361    op.operationId("update"+r.getType());
362    RequestBodyWriter req = op.request();
363    req.description("The new state of the resource").required(true);
364    if (isJson())
365      req.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/"+r.getType());
366    if (isXml())
367      req.content("application/fhir+xml").schemaRef(specRef()+"/"+r.getType()+".xsd");
368
369    opOutcome(op.responses().defaultResponse());
370    ResponseObjectWriter resp = op.responses().httpResponse("200");
371    resp.description("the resource being returned after being updated");
372    if (r.getVersioning() != ResourceVersionPolicy.NOVERSION)
373      resp.header("ETag").description("Version from Resource.meta.version as a weak ETag").schema().type(SchemaType.string);
374    if (isJson())
375      resp.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/"+r.getType());
376    if (isXml())
377      resp.content("application/fhir+xml").schemaRef(specRef()+"/"+r.getType()+".xsd");
378    op.paramRef("#/components/parameters/rid");
379    op.paramRef("#/components/parameters/summary");
380    op.paramRef("#/components/parameters/format");
381    op.paramRef("#/components/parameters/pretty");
382    op.paramRef("#/components/parameters/elements");
383  }
384
385  private void generatePatch(CapabilityStatementRestResourceComponent r) {
386    OperationWriter op = makePathResId(r).operation("patch");
387    op.summary("Change the current state of the resource by providing a patch - a series of change commands");
388    op.operationId("patch"+r.getType());
389    RequestBodyWriter req = op.request();
390    req.description("The new state of the resource").required(true);
391    if (isJson()) {
392      req.content("application/json-patch+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/"+r.getType());
393      req.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/Parameters");
394    }
395    if (isXml()) {
396      req.content("application/xml-patch+xml").schemaRef(specRef()+"/"+r.getType()+".xsd");
397      req.content("application/fhir+xml").schemaRef(specRef()+"/Parameters.xsd");
398    }
399
400    opOutcome(op.responses().defaultResponse());
401    ResponseObjectWriter resp = op.responses().httpResponse("200");
402    resp.description("the resource being returned after being patched");
403    if (r.getVersioning() != ResourceVersionPolicy.NOVERSION)
404      resp.header("ETag").description("Version from Resource.meta.version as a weak ETag").schema().type(SchemaType.string);
405    if (isJson())
406      resp.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/"+r.getType());
407    if (isXml())
408      resp.content("application/fhir+xml").schemaRef(specRef()+"/"+r.getType()+".xsd");
409    op.paramRef("#/components/parameters/rid");
410    op.paramRef("#/components/parameters/summary");
411    op.paramRef("#/components/parameters/format");
412    op.paramRef("#/components/parameters/pretty");
413    op.paramRef("#/components/parameters/elements");
414  }
415
416  private void generateDelete(CapabilityStatementRestResourceComponent r) {
417    OperationWriter op = makePathResId(r).operation("delete");
418    op.summary("Delete the resource so that it no exists (no read, search etc)");
419    op.operationId("delete"+r.getType());
420    opOutcome(op.responses().defaultResponse());
421    ResponseObjectWriter resp = op.responses().httpResponse("204");
422    resp.description("If the resource is deleted - no content is returned");
423    if (r.getVersioning() != ResourceVersionPolicy.NOVERSION)
424      resp.header("ETag").description("Version from Resource.meta.version as a weak ETag").schema().type(SchemaType.string);
425    op.paramRef("#/components/parameters/rid");
426  }
427
428  private void generateCreate(CapabilityStatementRestResourceComponent r) {
429    OperationWriter op = makePathRes(r).operation("post");
430    op.summary("Create a new resource");
431    op.operationId("create"+r.getType());
432    RequestBodyWriter req = op.request();
433    req.description("The new state of the resource").required(true);
434    if (isJson())
435      req.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/"+r.getType());
436    if (isXml())
437      req.content("application/fhir+xml").schemaRef(specRef()+"/"+r.getType()+".xsd");
438
439    opOutcome(op.responses().defaultResponse());
440    ResponseObjectWriter resp = op.responses().httpResponse("200");
441    resp.description("the resource being returned after being updated");
442    if (r.getVersioning() != ResourceVersionPolicy.NOVERSION)
443      resp.header("ETag").description("Version from Resource.meta.version as a weak ETag").schema().type(SchemaType.string);
444    if (isJson())
445      resp.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/"+r.getType());
446    if (isXml())
447      resp.content("application/fhir+xml").schemaRef(specRef()+"/"+r.getType()+".xsd");
448    op.paramRef("#/components/parameters/summary");
449    op.paramRef("#/components/parameters/format");
450    op.paramRef("#/components/parameters/pretty");
451    op.paramRef("#/components/parameters/elements");
452  }
453
454  private void generateBatchTransaction(CapabilityStatementRestComponent csr) {
455    OperationWriter op = makePathSystem().operation("put");
456    op.summary("Batch or Transaction");
457    op.operationId("transaction");
458    RequestBodyWriter req = op.request();
459    req.description("The batch or transaction").required(true);
460    if (isJson())
461      req.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/Bundle");
462    if (isXml())
463      req.content("application/fhir+xml").schemaRef(specRef()+"/Bundle.xsd");
464
465    opOutcome(op.responses().defaultResponse());
466    ResponseObjectWriter resp = op.responses().httpResponse("200");
467    resp.description("Batch or Transaction response");
468    if (isJson())
469      resp.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/Bundle");
470    if (isXml())
471      resp.content("application/fhir+xml").schemaRef(specRef()+"/Bundle.xsd");
472    op.paramRef("#/components/parameters/format");
473    op.paramRef("#/components/parameters/pretty");
474  }
475
476  private void opOutcome(ResponseObjectWriter resp) {
477    resp.description("Error, with details");
478    if (isJson())
479      resp.content("application/fhir+json").schemaRef(specRef()+"/fhir.schema.json#/definitions/OperationOutcome");
480    if (isXml())
481      resp.content("application/fhir+xml").schemaRef(specRef()+"/OperationOutcome.xsd");    
482  }
483
484  private String specRef() {
485    String ver = context.getVersion();
486    if (Utilities.noString(ver))
487      return "https://hl7.org/fhir/STU3";
488    if (ver.startsWith("4.0"))
489      return "https://hl7.org/fhir/R4";
490    if (ver.startsWith("3.0"))
491      return "https://hl7.org/fhir/STU3";
492    if (ver.startsWith("1.0"))
493      return "https://hl7.org/fhir/DSTU2";
494    if (ver.startsWith("1.4"))
495      return "https://hl7.org/fhir/2016May";
496    return "https://build.fhir.org";    
497  }
498
499  private boolean isJson() {
500    for (CodeType f : source.getFormat()) {
501      if (f.getCode().contains("json"))
502        return true;
503    }
504    return false;
505  }
506
507  private boolean isXml() {
508    for (CodeType f : source.getFormat()) {
509      if (f.getCode().contains("xml"))
510        return true;
511    }
512    return false;
513  }
514
515  public PathItemWriter makePathSystem() {
516    PathItemWriter p = dest.path("/");
517    p.summary("System level operations");
518    p.description("System level operations");
519    return p;
520  }
521
522  public PathItemWriter makePathMetadata() {
523    PathItemWriter p = dest.path("/metadata");
524    p.summary("Access to the Server's Capability Statement");
525    p.description("All FHIR Servers return a CapabilityStatement that describes what services they perform");
526    return p;
527  }
528
529  public PathItemWriter makePathRes(CapabilityStatementRestResourceComponent r) {
530    PathItemWriter p = dest.path("/"+r.getType());
531    p.summary("Manager for resources of type "+r.getType());
532    p.description("The Manager for resources of type "+r.getType()+": provides services to manage the collection of all the "+r.getType()+" instances");
533    return p;
534  }
535
536  public PathItemWriter makePathResId(CapabilityStatementRestResourceComponent r) {
537    PathItemWriter p = dest.path("/"+r.getType()+"/{rid}");
538    p.summary("Read/Write/etc resource instance of type "+r.getType());
539    p.description("Access to services to manage the state of a single resource of type "+r.getType());
540    return p;
541  }
542
543  public PathItemWriter makePathResType(CapabilityStatementRestResourceComponent r) {
544    PathItemWriter p = dest.path("/"+r.getType());
545    p.summary("manage the collection of resources of type "+r.getType());
546    p.description("Access to services to manage the collection of all resources of type "+r.getType());
547    return p;
548  }
549
550  public PathItemWriter makePathResHistListType(CapabilityStatementRestResourceComponent r) {
551    PathItemWriter p = dest.path("/"+r.getType()+"/_history");
552    p.summary("Read past versions of resources of type "+r.getType());
553    p.description("Access to previous versions of resourcez of type "+r.getType());
554    return p;
555  }
556
557  public PathItemWriter makePathResHistListId(CapabilityStatementRestResourceComponent r) {
558    PathItemWriter p = dest.path("/"+r.getType()+"/{rid}/_history");
559    p.summary("Read past versions of resource instance of type "+r.getType());
560    p.description("Access to previous versions of a single resource of type "+r.getType());
561    return p;
562  }
563
564  public PathItemWriter makePathResHistId(CapabilityStatementRestResourceComponent r) {
565    PathItemWriter p = dest.path("/"+r.getType()+"/{rid}/_history/{hid}");
566    p.summary("Read a past version of resource instance of type "+r.getType());
567    p.description("Access a to specified previous version of a single resource of type "+r.getType());
568    return p;
569  }
570
571  public PathItemWriter makePathHistListSystem() {
572    PathItemWriter p = dest.path("/_history");
573    p.summary("Read a past version of resource instance of all types");
574    p.description("Access a previous versions of all types");
575    return p;
576  }
577
578  private boolean hasOp(CapabilityStatementRestComponent r, SystemRestfulInteraction opCode) {
579    for (SystemInteractionComponent op : r.getInteraction()) {
580      if (op.getCode() == opCode) 
581        return true;
582    }
583    return false;
584  }
585
586  private boolean hasOp(CapabilityStatementRestResourceComponent r, TypeRestfulInteraction opCode) {
587    for (ResourceInteractionComponent op : r.getInteraction()) {
588      if (op.getCode() == opCode) 
589        return true;
590    }
591    return false;
592  }
593
594  private String url(List<ContactPoint> telecom) {
595    for (ContactPoint cp : telecom) {
596      if (cp.getSystem() == ContactPointSystem.URL)
597        return cp.getValue();
598    }
599    return null;
600  }
601
602
603  private String email(List<ContactPoint> telecom) {
604    for (ContactPoint cp : telecom) {
605      if (cp.getSystem() == ContactPointSystem.EMAIL)
606        return cp.getValue();
607    }
608    return null;
609  }
610
611
612
613}