|
1 | | -# How to host Swagger API documentation with GitHub Pages |
2 | | -[<img alt="The blog of Peter Evans: How to Host Swagger Documentation With Github Pages" title="View blog post" src="https://peterevans.dev/img/blog-published-badge.svg">](https://peterevans.dev/posts/how-to-host-swagger-docs-with-github-pages/) |
| 1 | +# OSTI Interagency Data API DOI service |
3 | 2 |
|
4 | | -This repository is a template for using the [Swagger UI](https://github.com/swagger-api/swagger-ui) to dynamically generate beautiful documentation for your API and host it for free with GitHub Pages. |
| 3 | +This repository is intended to host online documentation for the OSTI Interagency Data API (IAD) |
| 4 | +REST API services. |
5 | 5 |
|
6 | | -The template will periodically auto-update the Swagger UI dependency and create a pull request. See the [GitHub Actions workflow here](.github/workflows/update-swagger.yml). |
| 6 | +About the service |
| 7 | +----------------- |
| 8 | +The Office of Scientific and Technical Information (OSTI) became a member and an allocation agency for DataCite in 2011. OSTI assigns Digital Object Identifiers (DOIs) to Department of Energy datasets and registers those DOIs with DataCite. The Interagency Data ID Service (IAD), developed and operated by OSTI, provides this same service to other U.S. Federal Agencies desiring to make their data available for citation and discovery long into the future. |
7 | 9 |
|
8 | | -The example API specification used by this repository can be seen hosted at [https://peter-evans.github.io/swagger-github-pages](https://peter-evans.github.io/swagger-github-pages/). |
| 10 | +The IAD REST API |
| 11 | +---------------- |
| 12 | +The IAD REST API is provided to clients in order to facilitate and maintain registration of Digital |
| 13 | +Object Identifiers (DOIs) for various text, data, or other media resources. These DOIs link directly |
| 14 | +to the work itself, or landing pages detailing information about the work. |
9 | 15 |
|
10 | | -## Steps to use this template |
11 | | - |
12 | | -1. Click the `Use this template` button above to create a new repository from this template. |
13 | | - |
14 | | -2. Go to the settings for your repository at `https://github.com/{github-username}/{repository-name}/settings` and enable GitHub Pages. |
15 | | - |
16 | | -  |
17 | | - |
18 | | -3. Browse to the Swagger documentation at `https://{github-username}.github.io/{repository-name}/`. |
19 | | - |
20 | | - |
21 | | -## Steps to manually configure in your own repository |
22 | | - |
23 | | -1. Download the latest stable release of the Swagger UI [here](https://github.com/swagger-api/swagger-ui/releases). |
24 | | - |
25 | | -2. Extract the contents and copy the "dist" directory to the root of your repository. |
26 | | - |
27 | | -3. Move the file "index.html" from the directory "dist" to the root of your repository. |
28 | | - ``` |
29 | | - mv dist/index.html . |
30 | | - ``` |
31 | | - |
32 | | -4. Copy the YAML specification file for your API to the root of your repository. |
33 | | -
|
34 | | -5. Edit [index.html](index.html) and change the `url` property to reference your local YAML file. |
35 | | - ```javascript |
36 | | - const ui = SwaggerUIBundle({ |
37 | | - url: "swagger.yaml", |
38 | | - ... |
39 | | - ``` |
40 | | - Then fix any references to files in the "dist" directory. |
41 | | - ```html |
42 | | - ... |
43 | | - <link rel="stylesheet" type="text/css" href="dist/swagger-ui.css" > |
44 | | - <link rel="icon" type="image/png" href="dist/favicon-32x32.png" sizes="32x32" /> |
45 | | - <link rel="icon" type="image/png" href="dist/favicon-16x16.png" sizes="16x16" /> |
46 | | - ... |
47 | | - <script src="dist/swagger-ui-bundle.js"> </script> |
48 | | - <script src="dist/swagger-ui-standalone-preset.js"> </script> |
49 | | - ... |
50 | | - ``` |
51 | | - |
52 | | -6. Go to the settings for your repository at `https://github.com/{github-username}/{repository-name}/settings` and enable GitHub Pages. |
53 | | -
|
54 | | -  |
55 | | - |
56 | | -7. Browse to the Swagger documentation at `https://{github-username}.github.io/{repository-name}/`. |
57 | | -
|
58 | | - The example API specification used by this repository can be seen hosted at [https://peter-evans.github.io/swagger-github-pages](https://peter-evans.github.io/swagger-github-pages/). |
| 16 | +The service is maintained by the Office of Scientific and Technical Information (OSTI). For additional |
| 17 | +information, see https://www.osti.gov/iad2/ or email [email protected]. |
0 commit comments