{"id":22967440,"url":"https://github.com/asewhy/doc-api-generator","last_synced_at":"2025-06-22T05:02:56.881Z","repository":{"id":57732469,"uuid":"453541036","full_name":"AseWhy/doc-api-generator","owner":"AseWhy","description":null,"archived":false,"fork":false,"pushed_at":"2023-04-04T11:24:01.000Z","size":3568,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-02T05:18:20.915Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AseWhy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-29T23:12:54.000Z","updated_at":"2022-09-07T20:16:24.000Z","dependencies_parsed_at":"2023-01-30T01:45:43.655Z","dependency_job_id":null,"html_url":"https://github.com/AseWhy/doc-api-generator","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/AseWhy/doc-api-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AseWhy%2Fdoc-api-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AseWhy%2Fdoc-api-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AseWhy%2Fdoc-api-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AseWhy%2Fdoc-api-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AseWhy","download_url":"https://codeload.github.com/AseWhy/doc-api-generator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AseWhy%2Fdoc-api-generator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261238890,"owners_count":23128877,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-14T21:13:01.757Z","updated_at":"2025-06-22T05:02:51.861Z","avatar_url":"https://github.com/AseWhy.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# doc-api-generator\n\nНебольшой модуль для генерации документации api, модуль работает в паке с модулем конверсий и без него работать не может.\n\n## Базовая конфигурация\n\nДля начала работы с модулем необходимо создать бин конфигурации, минимальный пример показан ниже:\n\n```java\nimport com.fasterxml.jackson.databind.ObjectMapper;\nimport io.github.asewhy.apidoc.ApiDocumentationConfiguration;\nimport io.github.asewhy.apidoc.IApiDocumentationConfiguration;\nimport io.github.asewhy.apidoc.annotations.EnableApiDocGeneration;\nimport io.github.asewhy.apidoc.descriptor.info.ApiInfo;\nimport org.springframework.beans.factory.annotation.Autowired;\nimport org.springframework.beans.factory.annotation.Value;\nimport org.springframework.context.annotation.Configuration;\nimport org.springframework.context.annotation.Profile;\n\n@Configuration\n@EnableApiDocGeneration\n@Profile({\"dev\", \"beta\", \"test\"})\npublic class DocumentationConfig implements ApiDocumentationConfiguration {\n    @Value(\"${spring.application.name}\")\n    protected String appName;\n    @Autowired\n    protected ObjectMapper objectMapper;\n\n    @Override\n    public ObjectMapper objectMapper() {\n        return objectMapper;\n    }\n\n    @Override\n    public ApiInfo api() {\n        return new ApiInfo(appName, \"2.2.8\");\n    }\n}\n```\n\nКонфигурация выше будет активировать документацию только в профилях dev, beta и test. После запуска документацию swagger\nможно будет увидеть по адресу api/docs/swagger, документация openapi будет доступна по адресу /api/docs/json/. На маршрутах\nс документацией можно отключить spring security:\n\n```java\nimport org.jetbrains.annotations.NotNull;\nimport org.springframework.context.annotation.Configuration;\nimport org.springframework.security.config.annotation.web.builders.HttpSecurity;\nimport org.springframework.security.oauth2.config.annotation.web.configuration.ResourceServerConfigurerAdapter;\n\n@Configuration\npublic class StorageResource extends ResourceServerConfigurerAdapter {\n    public void configure(@NotNull HttpSecurity http) throws Exception {\n        http.csrf()\n            .disable()\n            .authorizeRequests()\n                .antMatchers(\"/api/docs/**\")\n                .permitAll()\n            .anyRequest()\n        .authenticated();\n    }\n}\n```\n\nАдрес документации можно поменять, реализовав в конфигурации методы `apiPath` и `docsPath`.\n\n### Безопасность\n\nДля описания способа доступа к апи можно указать так-же используемый способ авторизации. Ниже приведен пример как это можно сделать\nв конфигурации документации просто реализовав метод интерфейса:\n\n```java\n\nimport io.github.asewhy.apidoc.ApiDocumentationConfiguration;\nimport io.github.asewhy.apidoc.IApiDocumentationConfiguration;\nimport io.github.asewhy.apidoc.annotations.EnableApiDocGeneration;\nimport org.springframework.context.annotation.Configuration;\nimport org.springframework.context.annotation.Profile;\n\n@Configuration\n@EnableApiDocGeneration\n@Profile({\"dev\", \"beta\", \"test\"})\npublic class DocumentationConfig implements ApiDocumentationConfiguration {\n    // ...\n\n    @Override\n    public ApiSecurityInfo security() {\n        var info = new ApiSecurityInfo();\n\n        info.addSecurity(\n            ApiHttpSecurity\n                .builder()\n                .scheme(ApiHttpSecurityScheme.bearer)\n                .name(\"HttpBearerSecurity\")\n            .build()\n        );\n\n        return info;\n    }\n\n    // ...\n}\n```\n\nКод выше позволит указывать bearer токен авторизации для тестирования апи прямо на странице. Для авторизации так-же доступны\nи другие способы, смотри пакет `io.github.asewhy.apidoc.descriptor.info`.\n\n### Кастомные фабрики схем\n\nС версии 1.5.1 можно поставлять кастомные фабрики схем в глобальный контекст спринга. После инициализации фабрики она будет использована для\nсоздания схем типов openapi.\n\nСоздать фабрику можно следующим образом:\n\n```java\nimport io.github.asewhy.apidoc.formats.openapi.schema.JsonSchema;\nimport io.github.asewhy.apidoc.formats.service.support.OpenApiJsonSchemaGenerator;\nimport io.github.asewhy.apidoc.formats.service.support.OpenApiSimpleTypeSchemaFactory;\nimport org.jetbrains.annotations.NotNull;\nimport org.springframework.stereotype.Component;\nimport paa.coder.noodleCriteriaBuilder.restFilter.NoodleRestFilter;\nimport paa.coder.noodleCriteriaBuilder.restFilter.payloads.RestFilter;\n\nimport java.util.HashSet;\n\n@Component\npublic class NoodleRestFilterSchemaGenerator implements OpenApiSimpleTypeSchemaFactory {\n    @Override\n    public JsonSchema create(Class\u003c?\u003e type, @NotNull OpenApiJsonSchemaGenerator context) {\n        return context.getSchemaForType(RestFilter.class, new HashSet\u003c\u003e());\n    }\n\n    @Override\n    public Class\u003c?\u003e getType() {\n        return NoodleRestFilter.class;\n    }\n}\n```\n\nВ методе getType нужно вернуть тип, который будет описывать создаваемая схема. Метод create создает схему, если схему невозможно создать\nон должен вернуть null, тогда будет использован стандартный механизм создания схемы. Фабрика будет использоваться во всех случаях, когда\nгенератор создает схему.\n\nНиже дополнительно приведен пример создания схемы для описания Instant класса.\n\n```java\nimport io.github.asewhy.apidoc.formats.openapi.schema.JsonSchema;\nimport io.github.asewhy.apidoc.formats.openapi.schema.ObjectSchema;\nimport io.github.asewhy.apidoc.formats.openapi.schema.StringSchema;\nimport io.github.asewhy.apidoc.formats.service.support.OpenApiJsonSchemaGenerator;\nimport io.github.asewhy.apidoc.formats.service.support.OpenApiSimpleTypeSchemaFactory;\nimport org.jetbrains.annotations.NotNull;\nimport org.springframework.stereotype.Component;\n\nimport java.time.Instant;\nimport java.util.HashMap;\nimport java.util.Set;\n\n@Component\npublic class NoodleRestFilterSchemaGenerator implements OpenApiSimpleTypeSchemaFactory {\n    @Override\n    public JsonSchema create(Class\u003c?\u003e type, @NotNull OpenApiJsonSchemaGenerator context) {\n        var properties = new HashMap\u003cString, JsonSchema\u003e();\n\n        properties.put(\"zone\", StringSchema.builder().build());\n        properties.put(\"date\", StringSchema.builder().format(\"date-time\").build());\n        \n        return ObjectSchema.builder()\n            .required(Set.of(\"zone\", \"date\"))\n            .properties(properties)\n            .additionalProperties(false)\n        .build();\n    }\n\n    @Override\n    public Class\u003c?\u003e getType() {\n        return Instant.class;\n    }\n}\n```\n\n### Аннотации\n\nПакет предоставляет свои аннотации для настройки того как будет отображаться документация:\n\n| Аннотация   | Описание                                                                                                                                                                                                                                                                            | Пример                                                                                                                                                                                                                                                                                                                           |\n|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Description | Описание Поля/Метода/Контроллера/ДТО. Аннотация позволяет указать локализованное описание аннотируемой сущности                                                                                                                                                                     | @Description(\"Hello world\")                                                                                                                                                                                                                                                                                                      |\n| Example     | Пример для ДТО. Можно указать только над классом, предоставляет информацию о том какой пример отображать. Если аннотация отсутствует то swagger то генерирует пример автоматически. Пример должен быть предоставлен в том же формате что может обработать поставляемый ObjectMapper | @Example(\"\"\"\u003cbr\u003e　{\u003cbr\u003e　　\"foo\": \"bar\",\u003cbr\u003e　　\"baz\": \"bar\"\u003cbr\u003e　}\u003cbr\u003e\"\"\")                                                                                                                                                                                                                                                            |\n| Method      | Информация о методе АПИ, можно указать варианты ответа сервера, вплоть до статусов ответа и тела ответа, можно указать политики безопасности и описание самого метода.                                                                                                              | @Method(\u003cbr\u003e　response = {\u003cbr\u003e　　@Response(\u003cbr\u003e　　　type = SomeOtherClass.class,\u003cbr\u003e　　　value = HttpStatus.BAD_REQUEST,\u003cbr\u003e　　　description = @Description(\"Some description\")\u003cbr\u003e　　),\u003cbr\u003e　　@Response(\u003cbr\u003e　　　description = @Description(\"Success description\")\u003cbr\u003e　　)\u003cbr\u003e　},\u003cbr\u003e　description = @Description(\"\"\"Описание метода\"\"\")\u003cbr\u003e) |\n| Response    | Информация об ответе сервера, можно указать статус код и тело возможного ответа                                                                                                                                                                                                     | @Response(\u003cbr\u003e　description = @Description(\"Success description\")\u003cbr\u003e)                                                                                                                                                                                                                                                            |\n| Hidden      | Скрыть Поле/Метод/Контроллер/ДТО от взора сканера апи. Все аннотируемое этой аннотацией будет проигнорированною                                                                                                                                                                     | @Hidden                                                                                                                                                                                                                                                                                                                          |\n| Body        | Пометить параметр метода как тело запроса, если используется не стандартная аннотация спринг.                                                                                                                                                                                       | @Body                                                                                                                                                                                                                                                                                                                            |","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasewhy%2Fdoc-api-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasewhy%2Fdoc-api-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasewhy%2Fdoc-api-generator/lists"}