使用Swagger整合SpringMVC自动生成Restful接口文档

最新推荐文章于 2024-01-17 22:40:40 发布

chuyi1926

最新推荐文章于 2024-01-17 22:40:40 发布

阅读量168

点赞数

文章标签： java json 人工智能

原文链接：https://my.oschina.net/sluggarddd/blog/719532

版权

相信这一篇《Restful形式接口文档生成之Swagger与SpringMVC整合手记》大家都已经看过了。

根据这一篇blog搭建而出的是Swagger1.2的服务。现在最新的swagger-ui的validator已经通不过了。所以费了点劲升级到2.0，顺便记录一下。

相比于1.2，2.0的集成要简单不少。

MAVEN依赖

 <!-- 生成api文档-->
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>${springfox.swagger2.version}</version>
</dependency>

有一点需要注意的是，springfox-swagger2是依赖springframework的webmvc、web、context的，需要注意自己使用的版本，避免造成版本间的冲突，从而在中央库中寻找合适的springfox版本。

案例：一开始我用的版本是springfox 2.1.2，spring版本是4.2.5，然而springfox 2.1.2使用了spring 4.0.1里面的api。4.2.5是没有的，所以一直启动失败，切换至最新的2.5.1之后表现正常。

简单配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
//                .paths(PathSelectors.regex("/*"))
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfo(
                "标题",
                "描述",
                "版本号",
                "API TOS",
                new Contact("邮箱地址", "", ""),
                "API License",
                "API License URL"
        );

    }
}

其中Docket里面还有许多自定义的设置可以配置，这里就不赘述的，可以参考官网文档。

简单试用

@Api(tags = {"我是分类名"}, description = "我是描述")
@RestController
@RequestMapping("/swaggertest")
public class TestController {

    @ApiOperation("我是接口")
    @RequestMapping(value = "/test", method = RequestMethod.GET)
    public void test(@ApiParam(name = "用户id") @RequestParam("uid") String uid) {

    }
}

常用的三个annotation@APi、@ApiOperation、@ApiParam就可以满足百分之90的需求了。我在上面写了标注性质的描述，可以对照下面的图片看。

值得一提的是，他可以自动识别springmvc的annotation如RequestMapping,RequestParam，这倒是省事不少。

效果如下：

这时候运行你的web程序，访问http://{host}:{port}/{projectRoot}/v2/api-docs

就可以看到一长串定义的json。这就是用于swagger-ui展示的玩意儿。

接下来就是swagger-ui的部署了

如果你想在原项目中集成。

1、将swagger-ui从github上clone下来 https://github.com/swagger-api/swagger-ui

2、将其dist目录下的所有文件拷贝到自己webapp/swagger下

3、在spring配置文件中加上下面这句，使其html可以直接访问

<mvc:resources mapping="/swagger/**" location="/WEB-INF/swagger/"/>

4、访问http://{host}:{port}/{projectRoot}/swagger/index.html

5、在搜索栏搜索上面提到的提供json的地址即可

如果swagger-ui另外部署

1、你可以直接按照github上的教程使用node，跑起来

2、如果你不会node或者不想用，用你springmvc的经验搭建一个空项目把刚刚dist的东西丢进去，让其能直接访问/dist/index.html。

3、在搜索栏查看你想知道restapi文档的服务

4、会发现对方因为cors拒绝访问

5、需要在对方的web.xml中加入


    <!-- 发布记得删除-->

    <filter>
        <filter-name>CorsFilter</filter-name>
        <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>CorsFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

转载于:https://my.oschina.net/sluggarddd/blog/719532