springboot+swagger 自动生成 restful 文档及在线调试

本贴最后更新于 2339 天前,其中的信息可能已经时移世异

spring-boot-swagger-starter

本文项目已发布到 github,欢迎 fork 点赞。
https://github.com/wangyuheng/spring-boot-swagger-starter
已发布 maven 中央仓库,欢迎使用。

    <dependency>
        <groupId>com.github.wangyuheng</groupId>
        <artifactId>swagger-starter</artifactId>
        <version>0.0.1</version>
    </dependency>

swagger

swagger 可以快速生成 restful 接口文档,并提供在线调试功能。通过 springboot 开发微服务时,swagger 文档可以极大的提高协作效率。

springfox

springfox 将 swagger 整合到 spring

定制 starter

1. 定义 swagger 属性

用于文档页面显示及接口扫描路径,并使用 @ConfigurationProperties 读取属性

    swagger:
      groupName: 分类(groupName)
      title: 标题(title)
      description: 介绍(description)
      termsOfServiceUrl: 服务URL(termsOfServiceUrl)
      version: 版本(version)
      contactName: 作者名(contactName)
      contactUrl: 作者主页(contactUrl)
      contactEmail: 作者邮箱(contactEmail)
      paths: /upload.*,/category.*
      license:
      licenseUrl:
import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties(prefix = "swagger")
public class SwaggerProperty {

    private String groupName;
    private String title;
    private String description;
    private String termsOfServiceUrl;
    private String version;
    private String license;
    private String licenseUrl;
    //Contact
    private String contactName;
    private String contactUrl;
    private String contactEmail;
    private String[] paths;
}

2.设置 swagger 自动配置类

重点在于**@EnableSwagger2 及声明 Docket**

    import com.google.common.base.Predicate;
    import org.springframework.beans.factory.annotation.Autowired;
    import org.springframework.boot.context.properties.EnableConfigurationProperties;
    import org.springframework.context.annotation.Bean;
    import pro.hemo.swagger.config.SwaggerProperty;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    import static com.google.common.base.Predicates.or;
    import static springfox.documentation.builders.PathSelectors.regex;
    
    @EnableSwagger2
    @EnableConfigurationProperties(SwaggerProperty.class)
    public class SwaggerAutoApplication {
    
        @Autowired
        private SwaggerProperty swaggerProperty;
    
        @Bean
        public Docket docket() {
            checkValid(swaggerProperty);
            Predicate<String>[] selector = new Predicate[]{};
            if (null != swaggerProperty.getPaths() && swaggerProperty.getPaths().length > 0) {
                selector = new Predicate[swaggerProperty.getPaths().length];
                for (int i = 0; i < selector.length; i++) {
                    selector[i] = regex(swaggerProperty.getPaths()[i]);
                }
            }
    
            return new Docket(DocumentationType.SWAGGER_2)
                    .groupName(swaggerProperty.getGroupName())
                    .apiInfo(apiInfo())
                    .select()
                    .paths(or(selector))
                    .build();
        }
    
        private void checkValid(SwaggerProperty swaggerProperty) {
        }
    
    
        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title(swaggerProperty.getTitle())
                    .description(swaggerProperty.getDescription())
                    .termsOfServiceUrl(swaggerProperty.getTermsOfServiceUrl())
                    .contact(new Contact(swaggerProperty.getContactName(), swaggerProperty.getContactUrl(), swaggerProperty.getContactEmail()))
                    .license(swaggerProperty.getLicense())
                    .licenseUrl(swaggerProperty.getLicenseUrl())
                    .version(swaggerProperty.getVersion())
                    .build();
        }
    
    }

3. 创建 spring.factories

用于指定 springboot 自动配置文件路径,目录为 src/main/resources/META-INF/spring.factories

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
pro.hemo.swagger.SwaggerAutoApplication

使用 starter

1. 添加依赖

通过 maven 添加 starter

    <dependency>
      <groupId>pro.hemo</groupId>
      <artifactId>swagger-starter</artifactId>
      <version>0.0.1-SNAPSHOT</version>
    </dependency>

因为没有发布到仓库,需要先将 starter 项目发布到本地仓库
SwaggerStarter 目录执行

    mvn clean install 

2. 编写 Restful 接口

Spring 可以很方便的编写 Restful 接口,可以添加**@Api**等注解,用于生成文档。注解在 io.swagger.annotations 包下,后续会介绍常用注解。

3. 添加配置文件

通过 path 指定接口扫描目录

swagger:
  groupName:
  title:
  description:
  termsOfServiceUrl:
  version:
  contactName:
  contactUrl:
  contactEmail:
  paths: /upload.*, /category.*
  license:
  licenseUrl:

4. 启动项目

启动 springboot 项目,访问 http://localhost:8080/swagger-ui.html 可以看到接口列表。
986143febd124470bb56298da717de2f-2017102823.36.45.png

这里有几点需要注意

  1. swagger-ui.html 为自动生成映射
  2. 注意静态资源不要被拦截
  3. swagger-ui.html 为页面,接口以 json 格式通过加载并渲染。json 地址为 http://localhost:8080/v2/api-docs?group
  • Java

    Java 是一种可以撰写跨平台应用软件的面向对象的程序设计语言,是由 Sun Microsystems 公司于 1995 年 5 月推出的。Java 技术具有卓越的通用性、高效性、平台移植性和安全性。

    3165 引用 • 8206 回帖
  • Spring

    Spring 是一个开源框架,是于 2003 年兴起的一个轻量级的 Java 开发框架,由 Rod Johnson 在其著作《Expert One-On-One J2EE Development and Design》中阐述的部分理念和原型衍生而来。它是为了解决企业应用开发的复杂性而创建的。框架的主要优势之一就是其分层架构,分层架构允许使用者选择使用哪一个组件,同时为 JavaEE 应用程序开发提供集成的框架。

    938 引用 • 1456 回帖 • 163 关注
  • Swagger

    Swagger 是一款非常流行的 API 开发工具,它遵循 OpenAPI Specification(这是一种通用的、和编程语言无关的 API 描述规范)。Swagger 贯穿整个 API 生命周期,如 API 的设计、编写文档、测试和部署。

    26 引用 • 35 回帖 • 7 关注

相关帖子

欢迎来到这里!

我们正在构建一个小众社区,大家在这里相互信任,以平等 • 自由 • 奔放的价值观进行分享交流。最终,希望大家能够找到与自己志同道合的伙伴,共同成长。

注册 关于
请输入回帖内容 ...
  • 以前 api 是前端定,就要自己手写。现在后端定,虽然方便多了,但是总需要修改来满足前端的界面,有时候还需要转换。。。

    1 回复
  • 其他回帖
  • crick77
    作者

    api 就是双方签订的契约嘛,如果是同时开发,肯定是需要前后双方协定。

    这个也可以直接获取 json, 然后前端根据这个自己定制样式活着生成代码。

    根据前后端分离的架构,应该有一层用来组装接口数据,渲染页面。目前公司是用的 node 层来做

  • 我想要个根据 apimocker 生成 swagger 的。

  • crick77
    作者

    欢迎试用 & 提 issue 😘

    1 回复
  • 查看全部回帖