mirror/Hangar
2
0
Fork 0
mirror of https://github.com/HangarMC/Hangar.git synced 2025-01-18 14:14:50 +08:00
Code Issues Packages Projects Releases Wiki Activity

adjust api docs a bit, fix one project api, fix swagger styling

Browse Source 
Signed-off-by: MiniDigger <admin@minidigger.me>
This commit is contained in:
MiniDigger 2021-05-15 13:41:36 +02:00
parent 1511c85619
commit 56bb8452de
4 changed files with 28 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
frontend/pages/api.vue
View File

@ -67,7 +67,7 @@ export default class ApiPage extends HangarComponent {
.info hgroup.main a {
display: none;
}
.info {
.wrapper .info {
background-color: unset !important;
border-color: unset !important;
margin: 2rem 0;

40
src/main/java/io/papermc/hangar/config/SwaggerConfig.java
View File

@ -10,7 +10,6 @@ import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.RequestParameterBuilder;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.ParameterStyle;
import springfox.documentation.service.ParameterType;
import springfox.documentation.service.RequestParameter;
@ -34,26 +33,29 @@ public class SwaggerConfig {
ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Hangar API")
.description(" This page describes the format for the current Hangar REST API, in addition to common questions when using it. " +
"Note that anything that starts with `_` should be considered internal, and can change at a moment's notice. Do not use it. " +
"<h2>Authentication and authorization</h2> There are two ways to consume the API. Keyless, and using an API key. " +
"<h3>Keyless</h3> When using keyless authentication you only get access to public information, but don't need to worry about creating and storing an API key. " +
"<h3>API</h3> Keys If you need access to non-public actions, or want to do something programatically, you likely want an API key. " +
"These can be created by going to your user page and clicking on the key icon. " +
"<h3>Authentication</h3> Once you know how you want to authenticate you need to create a session. You can do this by `POST`ing to `/authenticate`. " +
"If you're using keyless authentication that's it. If you have an API key, you need to specify it in the Authorization header like so `Authorization: HangarApi apikey=\"foobar\"`. " +
"<h3>Authorization</h3> Once you do that you should receive an session. This is valid for a pre-defined set of time. When it expires, you need to authenticate again. " +
"To use it, set it in the Authorization header like so `Authorization: HangarApi session=\"noisses\"`. For more info about authentication, see [here](#/Authentification/authenticate). " +
.description("This page describes the format for the current Hangar REST API, in addition to common questions when using it.<br>" +
"Note that all routes **not** listed here should be considered **internal**, and can change at a moment's notice. **Do not use them**." +
"<h2>Authentication and Authorization</h2>" +
"There are two ways to consume the API: Authenticated or Anonymous." +
"<h3>Anonymous</h3>" +
"When using anonymous authentication you only get access to public information, but don't need to worry about creating and storing an API key or handing JWTs." +
"<h3>Authenticated</h3>" +
"If you need access to non-public actions, or want to do something programmatically, you likely want an API key.<br>" +
"These can be created by going to your user page and clicking on the key icon.<br>" +
"API keys allow you to impersonate yourself, so they should be handled like passwords, **never** share them!" +
"<h4>Authentication</h4>" +
"Once you have an api key, you need to authenticate yourself. For that you `POST` your API Key to `/api/v1/authenticate?apiKey=yourKey`. The response will contain your JWT.<br>" +
"You want to store that JWT and send it with every request. It's valid for a certain amount of time, the token itself contains a field with a timestamp when it will expire. If it expired, you want to reauthenticate yourself." +
"<h4>Authorization</h4>" +
"Now that you have your JWT, you want to set it in the Authorization header for every request like so `Authorization: HangarAuth your.jwt`. The request will be then executed with the permission scope of your api key." +
"<br>" +
"While talking about headers. Please also set a useful User-Agent header. This allows us to better identify loads and need for potentially new endpoints." +
"<h2>FAQ</h2>" +
"<h3>Why do I need to create a new session when I just want to get some public info?</h3>" +
"We're working on a session-less authentification for public endpoints. " +
"<h3>What format does dates have?</h3>" +
"Standard ISO types. Where possible we use the OpenAPI format modifier. You can view it's meanings [here](https://swagger.io/docs/specification/data-models/data-types/#format).")
.license("Unlicense")
.licenseUrl("http://unlicense.org")
.termsOfServiceUrl("")
"<h3>What format do dates have?</h3>" +
"Standard ISO types. Where possible, we use the OpenAPI format modifier. You can view its meanings [here](https://swagger.io/docs/specification/data-models/data-types/#format)." +
"<h3>Are there rate-limits? What about caching?</h3>" +
"There are currently no rate limits. Please don't abuse that fact. If applicable, always cache the responses. The Hangar API itself is cached by CloudFlare and internally.")
.version("1.0")
.contact(new Contact("MiniDigger", "https://minidigger.me", "admin@minidigger.me"))
.build();
}

9
src/main/java/io/papermc/hangar/controller/api/v1/interfaces/IAuthenticationController.java
View File

@ -11,19 +11,18 @@ import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
@Api(tags = "Sessions (Authentication)", produces = MediaType.APPLICATION_JSON_VALUE)
@RequestMapping(path = "/api/v1", produces = MediaType.APPLICATION_JSON_VALUE, method = RequestMethod.POST)
@Api(tags = "Authentication", produces = MediaType.APPLICATION_JSON_VALUE)
@RequestMapping(path = "/api/v1", produces = MediaType.APPLICATION_JSON_VALUE)
public interface IAuthenticationController {
@ApiOperation(
value = "Creates an API JWT",
nickname = "authenticate",
notes = "Creates a new API JWT. Pass an API key to create an authenticated session. When passing an API key, you should use the scheme `HangarAuth`, and parameter `apikey`. An example would be `Authorization: HangarAuth <apikey>`. The returned JWT should be specified in all following request as the parameter `token`.",
notes = "`Log-in` with your API key, in order to be able to call other endpoints authenticated. The returned JWT should be specified in all following request as a header like this `Authorization: HangarAuth your.jwt`.",
authorizations = @Authorization(value = "Key"),
tags = "Sessions (Authentication)"
tags = "Authentication"
)
@ApiResponses({
@ApiResponse(code = 200, message = "Ok"),

2
src/main/java/io/papermc/hangar/db/dao/v1/ProjectsApiDAO.java
View File

@ -54,6 +54,8 @@ public interface ProjectsApiDAO {
" p.license_url," +
" p.keywords," +
" p.forum_sync," +
" p.topic_id," +
" p.post_id," +
" p.donation_enabled," +
" p.donation_email," +
" p.donation_default_amount," +