Commit Graph

15 Commits

Author SHA1 Message Date
David Taylor c65c23b48d
DEV: Fix openapi definition logo URL (#17038)
See 887e4087d5
2022-06-08 13:10:20 +01:00
David Taylor c9dab6fd08
DEV: Automatically require 'rails_helper' in all specs (#16077)
It's very easy to forget to add `require 'rails_helper'` at the top of every core/plugin spec file, and omissions can cause some very confusing/sporadic errors.

By setting this flag in `.rspec`, we can remove the need for `require 'rails_helper'` entirely.
2022-03-01 17:50:50 +00:00
Jarek Radosz 2fc70c5572
DEV: Correctly tag heredocs (#16061)
This allows text editors to use correct syntax coloring for the heredoc sections.

Heredoc tag names we use:

languages: SQL, JS, RUBY, LUA, HTML, CSS, SCSS, SH, HBS, XML, YAML/YML, MF, ICS
other: MD, TEXT/TXT, RAW, EMAIL
2022-02-28 20:50:55 +01:00
Martin Brennan 19089f21d2
DEV: Add API docs for uploads and API doc watcher (#15387)
This commit adds API documentation for the new upload
endpoints related to direct + multipart external uploads.

Also included is a rake task which watches the files in
the spec/requests/api directory and calls a script file
(spec/regenerate_swagger_docs) whenever one changes. This
script runs rake rswag:specs:swaggerize and then copies
the openapi.yml file over to the discourse_api_docs repo
directory, and hits a script there to convert the YML to
JSON so the API docs are refreshed while the server is
still running. This makes the loop of making a doc change
and seeing it in the local server much faster.

The rake task is rake autospec:swagger
2021-12-23 08:40:15 +10:00
Blake Erickson 4a4881613b
DEV: Refactor the api docs for the user endpoint (#14377)
Due to the way that rswag expands shared components we were getting this
warning when linting our api docs:

```
Component: "user_response" is never used.
```

This change refactors the `api/users_spec.rb` file so that it uses the
new way of doing things with a separate `user_get_response.json` schema
file rather then the old way of loading a shared response inside of the
swagger_helper.rb file.
2021-09-20 10:04:57 -06:00
Blake Erickson d500c436c6
DEV: Add license field to api docs info section (#14248)
One of the fields that should be present for openapi docs is the "license"
field.

https://spec.openapis.org/oas/latest.html#infoObject

Our API docs already had a license, so this commit just specifies that
and provides a link to it.
2021-09-07 10:35:56 -06:00
Blake Erickson 65f6d46045
DEV: Fix several type issues with the api docs (#14016)
`nullable` is no longer a valid type, and types also can't be an empty
string, so just bringing a number of issues with types in compliance
with the openapi spec.
2021-08-12 12:25:17 -06:00
Blake Erickson 1799944a04
DEV: Specify the latest openapi spec version (#14012)
The latest openapi spec version is v3.1.0

 https://spec.openapis.org/oas/v3.1.0

Specifying the latest version will allow our openapi spec linter to use
this version and allow use to use the new type format that allows for
specifying a type as "null", which we need because sometimes our api
responses include null values instead of a "string", "integer", or
"object" type.

See: https://stackoverflow.com/a/48114322/588458
2021-08-11 12:38:02 -06:00
Bianca Nenciu 87c1e98571
FEATURE: Let users select flair (#13587)
User flair was given by user's primary group. This PR separates the
two, adds a new field to the user model for flair group ID and users
can select their flair from user preferences now.
2021-07-08 10:46:21 +03:00
Blake Erickson 8a001c2fe3
api docs example (#11997)
* DEV: Escape backslashes in curl example

We need to escape these backslashes otherwise they get filtered out when
generating the api docs.

* FIX: uniqItems should be uniqueItems
2021-02-08 10:09:44 -07:00
Blake Erickson 91fb298510
DEV: Add description and logo to api docs (#11984)
* DEV: Add description and logo to api docs

* Rename method to avoid name collision
2021-02-04 18:43:40 -07:00
Blake Erickson 798b479e0d
DEV: More API Doc improvements (#11849)
- Create helper wrapper method `load_spec_schema(name)`
- A minor change to tag_group_create response schema
- Document the uploads endpoint
2021-01-26 07:38:46 -07:00
Blake Erickson 7434116933
DEV: Add schema checking to api doc testing (#11721)
* DEV: Add schema checking to api doc testing

This commit improves upon rswag which lacks schema checking. rswag
really only checks that the https status matches, but this change adds
in the json-schema_builder gem which also has schema validation.

Now we can define schemas for each of our requests/responses in the
`spec/requests/api/schemas` directory which will make our documentation
specs a lot cleaner.

If we update a serializer by either adding or removing an attribute the
tests will now fail (this is a good thing!). Also if you change the type
of an attribute say from an array to a string the tests will now fail.
This will help significantly with keeping the docs in sync with actual
code changes! Now if you change how an endpoint will respond you will
have to update the docs too in order for the tests to pass. :D

This PR is inspired by:

 https://www.tealhq.com/post/how-teal-keeps-their-api-tests-and-documentation-in-sync

* Swap out json schema validator gem

Swapped out the outdated json-schema_builder gem with the json_schemer
gem.

* Add validation fields to schema

In order to have "strict" validation we need to add
`additionalProperties: false` to the schema, and we need to specify
which attributes are required.

Updated the debugging test output to print out the error details if
there are any.
2021-01-21 16:28:08 -07:00
Blake Erickson fa4af17580
DEV: Document get user by external_id api endpoint (#11717)
Added GET user by external_id to the api docs.
Fixed `/users/{username}` docs to be `/u/{username}`

Extracted out common user response into a shared helper.
2021-01-14 16:59:58 -07:00
Blake Erickson a93ef2926d
DEV: Add rswag to aid in api documention (#9546)
Adding in rswag will allow us to write spec files to document and test
our api.
2020-04-27 16:40:07 -06:00