Swagger-API文档管理

爱吃糖的靓仔

已于 2023-04-13 16:25:35 修改

阅读量594

点赞数

分类专栏： # 框架使用文章标签： java spring boot 开发语言

于 2019-11-25 17:37:45 首次发布

本文链接：https://blog.csdn.net/qq_42292373/article/details/103237484

版权

框架使用专栏收录该内容

23 篇文章 0 订阅

订阅专栏

文章目录

1.代码地址
2.Swagger好处在哪里
3.SpringBoot整合Swagger
4.参数的生成
5.微服务网关Zuul集群整合Swagger

1.代码地址

链接：https://pan.baidu.com/s/1KbVTpA5BuRlNzKESTj4Y-A 
提取码：y0yx

2.Swagger好处在哪里

传统开发的几个痛处

对API文档进行更新的时候，需要通知前端开发人员，导致文档更新交流不及时；
API接口返回信息不明确
大公司中肯定会有专门文档服务器对接口文档进行更新。
缺乏在线接口测试，通常需要使用相应的API测试工具，比如postman、SoapUI等
接口文档太多，不便于管理

Swagger具有以下优点

功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

为了解决传统API接口文档维护的问题，为了方便进行测试后台Restful接口并实现动态的更新，因而引入Swagger接口工具。

3.SpringBoot整合Swagger

1. 依赖文件

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.1.RELEASE</version>
    </parent>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>Finchley.M7</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <dependencies>
        <!-- SpringBoot整合Web组件 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!-- SpringBoot整合eureka客户端 -->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
        </dependency>
        <!-- swagger2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
    </dependencies>
    <!-- 注意： 这里必须要添加， 否者各种依赖有问题 -->
    <repositories>
        <repository>
            <id>spring-milestones</id>
            <name>Spring Milestones</name>
            <url>https://repo.spring.io/libs-milestone</url>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>

</project>

2.配置文件

@Configuration
//开启swagger功能
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                // 生成扫包的范围
                .apis(RequestHandlerSelectors.basePackage("com.disney.api")).paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("微服务电商系统").description("Java分布式")
                .termsOfServiceUrl("http://www.baidu.com")
                // 文档的版本号
                .version("1.0").build();
    }

}

3. controller

@RestController
//对于的接口的描述
@Api("测试控制器")
public class SwaggerController {

    @ApiOperation("swagger接口")
    @GetMapping("/index") //这里尽可能用restful风格的请求路径,不然写requestMapping的话,任何的形式的请求都会有,很乱
    public String getIndex(){
        return "index";
    }
}

4.启动类

@SpringBootApplication
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class,args);
    }
}

访问http://localhost:8989/swagger-ui.html#/swagger-controller 即可看到如下界面
在这里插入图片描述

4.参数的生成

  @ApiOperation("参数的获取")
    @GetMapping("/getname")
    @ApiImplicitParam(name = "name",value = "用户参数",required = true,dataType = "String")
    public String getName(String name){
     return name;
    }

在这里插入图片描述

5.微服务网关Zuul集群整合Swagger

所面临的的问题: Swagger是针对单独所在项目接口进行生成,那么微服务的所有服务的接口,如何整合在一起呢?

相关的SpirngCloud Zuul网关的可以参考https://blog.csdn.net/qq_42292373/article/details/103227925

分别在Member和Order项目,Zuul网关添加依赖

       <dependency>
            <groupId>com.spring4all</groupId>
            <artifactId>swagger-spring-boot-starter</artifactId>
            <version>1.7.0.RELEASE</version>
        </dependency>

2,启动类改变(Order 和Member )

@SpringBootApplication
@EnableFeignClients
@EnableEurekaClient
@EnableHystrix
//生成swagger文档
@EnableSwagger2Doc
public class AppOrder {
    public static void main(String[] args) {
        SpringApplication.run(AppOrder.class, args);
    }
}

3.增加扫描接口的路径

###服务启动端口号
server:
  port: 8020
###服务名称(服务注册到eureka名称)
spring:
  application:
    name: app-itmayiedu-order
###服务注册到eureka地址
eureka:
  client:
    service-url:
      defaultZone: http://localhost:8100/eureka
    ###因为该应用为注册中心，不会注册自己
    register-with-eureka: true
    ###是否需要从eureka上获取注册信息
    fetch-registry: true
###设置feign客户端超时时间
ribbon:
  ###指的是建立连接所用的时间，适用于网络状况正常的情况下，两端连接所用的时间。
  ReadTimeout: 5000
  ###指的是建立连接后从服务器读取到可用资源所用的时间。
  ConnectTimeout: 5000
#feign:
#  hystrix:
#enabled: true
swagger:
  base-package: com.member.impl  # 扫描的路径

4,对接口的说明

@RestController
@Api("订单服务接口")
public class OrderServiceImpl  implements IOrderService {

    @Autowired
    private MemberServiceFeigin memberServiceFeigin;

    @RequestMapping("/orderToMember")
    public String orderToMember(String name) {
        UserEntity user = memberServiceFeigin.getMember(name);
        return user == null ? "没有找到用户信息" : user.toString();
    }
//    @HystrixCommand(fallbackMethod = "fallbackMethod")
    @ApiOperation("getIndex")
    @RequestMapping("/getIndex")
    public String getIndex(){
        return memberServiceFeigin.getIndex();
    }

    public String fallbackMethod(){
        return "对不起当前方法不可用";
    }
}

在Zuul网关服务中添加配置和启动类的修改

@SpringBootApplication
@EnableEurekaClient
@EnableZuulProxy
@EnableSwagger2Doc
public class ZuulApplication {
    public static void main(String[] args) {
        SpringApplication.run(ZuulApplication.class,args);
    }

    @RefreshScope
    @ConfigurationProperties("zuul")
    public ZuulProperties zuulProperties(){
        return new ZuulProperties();
    }


    // 添加文档来源
    @Component
    @Primary
    class DocumentationConfig implements SwaggerResourcesProvider {
        @Override
        public List<SwaggerResource> get() {
            List resources = new ArrayList<>();
            //arg 根据服务别名,确定文档的目标
            //arg1 通过网关进行查询API文档
            //arg2
            resources.add(swaggerResource("app-itmayiedu-member", "/api-member/v2/api-docs", "2.0"));
            resources.add(swaggerResource("app-itmayiedu-order", "/api-order/v2/api-docs", "2.0"));
            return resources;
        }

        private SwaggerResource swaggerResource(String name, String location, String version) {
            SwaggerResource swaggerResource = new SwaggerResource();
            swaggerResource.setName(name);
            swaggerResource.setLocation(location);
            swaggerResource.setSwaggerVersion(version);
            return swaggerResource;
        }
    }

}

然后访问http://localhost:81/swagger-ui.html或者http://localhost:82/swagger-ui.html 任意网关端口号,即可看到如下的界面

在这里插入图片描述
注意:如果有ZullFilter的话,可能会出现这个界面,所以上面的图片,我注释掉了ZuulFilter,也请各位大佬,可以分享下这个解决问题的建议,在这里,提前谢谢你们

爱吃糖的靓仔

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
Swagger-API文档管理

文章目录1.代码地址2.Swagger好处在哪里3.SpringBoot整合Swagger4.参数的生成5.微服务网关Zuul集群整合Swagger1.代码地址链接：https://pan.baidu.com/s/1KbVTpA5BuRlNzKESTj4Y-A 提取码：y0yx2.Swagger好处在哪里传统开发的几个痛处对API文档进行更新的时候，需要通知前端开发人员，导致文档更...
复制链接

扫一扫

专栏目录