spring boot / cloud (三) 集成springfox-swagger2构建在线API文档

spring boot / cloud (三) 集成springfox-swagger2构建在线API文档

前言

不能同步更新API文档会有什么问题?

理想情况下,为所开发的服务编写接口文档,能提高与周边系统对接联调的效率.但前提条件是,服务和API文档必须是同步更新的,如果不能保证同步,那接口文档就会流于形式,不仅不能起到应有的作用,甚至某些情况下,甚至会误导对接的系统,导致更低效率的沟通.

思路

  • 根据现有的服务定义来自动生成接口文档

实现

1.pom.xml集成springfox-swagger2

    <!-- swagger2 -->
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>${springfox-swagger2.version}</version>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>${springfox-swagger2.version}</version>
    </dependency>

2.创建Swagger2Config类

@Configuration
@EnableSwagger2
public class Swagger2Config {


}

3.配置Bean

  @Bean
  public WebMvcConfigurerAdapter addResourceHandlers() {
    return new WebMvcConfigurerAdapter() {
      @Override
      public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
      }
    };
  }

注意点 : 版本号和项目名称可在配置文件中定义(从pom中取)

 @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
        .apis(RequestHandlerSelectors.basePackage("com.egridcloud")).paths(PathSelectors.any())
        .build();
  }

  private ApiInfo apiInfo() {
    ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
    apiInfoBuilder.title(this.projectName + " online api document");
    apiInfoBuilder.version(version);
    return apiInfoBuilder.build();
  }

4.使用@Api来标记controller

@RestController
@RequestMapping("demo")
@Api(value = "demo", 
    consumes = "application/json", 
    produces = "application/json",
    protocols = "http")
public class DemoController {

}

5.使用@ApiOperation来标记方法

  @ApiOperation(value = "add", notes = "add")
  @RequestMapping(value = "add", method = RequestMethod.GET)
  public RestResponse<Integer> add(Integer a, Integer b) {
    return new RestResponse<>(demoService.add(a, b));
  }

6.使用@ApiImplicitParams和@ApiImplicitParam来标参数

  @ApiOperation(value = "add", notes = "add")
  @ApiImplicitParams({
      @ApiImplicitParam(paramType = "query", name = "a", value = "a", required = true,
          dataType = "int"),
      @ApiImplicitParam(paramType = "query", name = "b", value = "a", required = true,
          dataType = "int") })
  @RequestMapping(value = "add", method = RequestMethod.GET)
  public RestResponse<Integer> add(Integer a, Integer b) {
    return new RestResponse<>(demoService.add(a, b));
  }

7.使用@ApiModel和@ApiModelProperty来标实体类

@ApiModel(description = "响应消息体")
public class RestResponse<T> implements Serializable {

  /**
   * 
   * 描述 : id
   * 
   */
  private static final long serialVersionUID = 1L;

  /**
   * 描述 : 响应ID
   */
  @ApiModelProperty(value = "响应ID", required = true, dataType = "string")
  private String id = UUID.randomUUID().toString();

  .............

}

结束

以上配置结束之后,启动项目,访问http://xxxxx/swagger-ui.html即可能够访问接口文档,并且直接可以做接口调用测试.

然后对于Swagger2这个组件,目前看下来就是对业务代码有一定的入侵,总之使用前请根据自身项目情况做好评估,不要盲目跟风.


想获得最快更新,请关注公众号

想获得最快更新,请关注公众号

  • 0
    点赞
  • 1
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
Spring Cloud Gateway是一个轻量级的API网关,用于微服务架构中路由、过滤和增强流量控制。为了将Swagger(一种常用的API文档生成工具)集成Spring Cloud Gateway中,你可以按照以下步骤操作: 1. 添加依赖:首先,你需要在你的`pom.xml`或`build.gradle`文件中添加Spring Cloud Gateway和Swagger相关的依赖。例如,如果你使用的是Maven,可能会包含这些依赖: ```xml <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-gateway</artifactId> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>3.x.x</version> <!-- 使用最新版本 --> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.x.x</version> </dependency> ``` 2. 配置 Swagger UI:在Spring Boot应用中,配置Swagger UI作为默认的UI界面。这通常通过修改`application.yml`或`application.properties`文件来完成: ```yaml spring: application: name: your-app-name springfox: ui: enabled: true path: /api-docs ``` `path`属性定义了Swagger UI的访问路径。 3. 注解支持:为了使Spring Cloud Gateway中的路由能够被Swagger识别,你可能需要在你的API控制器上添加`@EnableWebMvcEndpoint`注解(如果尚未添加),以便启用对Web MVC端点的支持。 4. 定义API接口:创建你的API接口,并用`@ApiOperation`、`@ApiParam`等注解来提供必要的元数据信息。这样Swagger才能正确解析并生成文档。 5. 自动扫描:确保你的API控制器在Spring的自动扫描范围内,Spring Cloud Gateway会自动发现并处理它们。 6. 启动应用:启动你的Spring Boot应用,然后访问`http://localhost:your-port/api-docs`(根据配置替换`your-port`),你应该能看到Swagger UI界面。

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值