1 В избранное 0 Ответвления 0

OSCHINA-MIRROR/largerfish-swagger-doc

Присоединиться к Gitlife
Откройте для себя и примите участие в публичных проектах с открытым исходным кодом с участием более 10 миллионов разработчиков. Приватные репозитории также полностью бесплатны :)
Присоединиться бесплатно
Клонировать/Скачать
Внести вклад в разработку кода
Синхронизировать код
Отмена
Подсказка: Поскольку Git не поддерживает пустые директории, создание директории приведёт к созданию пустого файла .keep.
Loading...
README.md

Документ

Документ (https://gitee.com/largerfish/swagger-doc/wikis/Home)

Swagger-Doc

Важное о проекте: что он решает

В целом, проект Swagger-Doc решает проблемы, с которыми сталкиваются многие пользователи при использовании Swagger. Он заменяет Springfox, который использует аннотации для создания документации, и предлагает более чистый и понятный способ создания документации на основе JavaDoc. Это позволяет снизить уровень загрязнения кода и упростить процесс изучения проекта.

Сравнение двух подходов

Автор приводит пример кода, написанного с использованием Springfox и Swagger-Doc, чтобы показать разницу между подходами. В примере кода с Springfox используются аннотации, которые могут загрязнять код. Пример кода со Swagger-Doc использует только стандартные аннотации Java. Автор считает, что такой подход может повысить эффективность работы разработчиков, так как они могут одновременно создавать документацию и код.

Проект Загрязнение кода Стоимость обучения Поддержка Springboot Уровень функциональности
Swagger-Doc Минимальное Низкая Поддерживается Ограниченный
Springfox Значительное Высокая Поддерживается Полный

Быстрый старт

Поскольку проект всё ещё находится в разработке, автор рекомендует установить его через локальный репозиторий Maven. Для этого необходимо выполнить следующие шаги:

  1. Установить проект в локальный репозиторий:
cd swagger-doc
mvn install
  1. Добавить зависимость в проект:
<repositories>
    <repository>
        <id>oszrh</id>
        <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.gitee.largerfish</groupId>
    <artifactId>swagger-core</artifactId>
    <version>1.1-SNAPSHOT</version>
</dependency>
  1. Настроить Spring Boot:
@EnableSwaggerDoc
public class SampleApplication {
    public static void main(String[] args) {
        SpringApplication springApplication = new SpringApplication(SampleApplication.class);
        springApplication.run(args);
    }

    @Bean
    public FilterRegistrationBean logFilterRegistrationBean() {
        FilterRegistrationBean filterRegistrationBean = new FilterRegistrationBean();
        filterRegistrationBean.setFilter(new FilterInterceptor());
        filterRegistrationBean.setName("logFilterRegistrationBean");
        filterRegistrationBean.setUrlPatterns(Arrays.asList("/*"));
        filterRegistrationBean.setOrder(1);
        return filterRegistrationBean;
    }

    @Bean
    public SwaggerDoc swaggerDoc() {
        Contact contact = new Contact();
        Info info = new Info();
        info.setTitle("Тестовый документ");
        contact.setEmail("542467660@qq.com");
        contact.setName("wk");
        contact.setUrl("http://git.oschina.net/wangkang_daydayup/swagger-doc");
        info.setDescription("Swagger-doc решает проблему загрязнения кода Springfox с помощью аннотаций. Используется JavaDoc для создания документации. Код становится чище, а стоимость обучения ниже.");
        info.setContact(contact);
        return new SwaggerDoc.SwaggerDocBuilder().addSkipAnnotations(SessionAttribute.class).withDoc("doc")
            .withDoc("Тестовый документ").withInfo(info).withHost("139.224.35.224")
            .addIgnoreControllers("swaggerController", "basicErrorController").build();
    }
}
  1. Собрать исходный код:
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-source-plugin</artifactId>
    <version>3.0.1</version>
    <executions>
        <execution>
            <id>attach-sources</id>
            <goals>
                <goal>jar-no-fork</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Собрать проект с исходным кодом:

#!/usr/bin/env bash
mvn clean -U process-resources package -Dmaven.test.skip=true
cp target/swagger-doc-demo-1.0-SNAPSHOT.jar source
  1. Создать Swagger UI: Скачать последнюю версию Swagger UI с GitHub: https://github.com/swagger-api/swagger-ui

Результаты

Проект Swagger-Doc предоставляет простой и эффективный способ создания документации для API. Он использует JavaDoc вместо аннотаций, что делает код более чистым и понятным.

Комментарии ( 0 )

Вы можете оставить комментарий после Вход в систему

Введение

Описание недоступно Развернуть Свернуть
Apache-2.0
Отмена

Обновления (2)

все

Участники

все

Недавние действия

Загрузить больше
Больше нет результатов для загрузки
1
https://api.gitlife.ru/oschina-mirror/largerfish-swagger-doc.git
git@api.gitlife.ru:oschina-mirror/largerfish-swagger-doc.git
oschina-mirror
largerfish-swagger-doc
largerfish-swagger-doc
master