springboot利用swagger构建api文档

一、引入jar

pom.xml

           <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>

二、配置

package com.lyon.swagger;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.async.DeferredResult;
import static com.google.common.base.Predicates.or;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import static springfox.documentation.builders.PathSelectors.regex;

@Configuration
public class Swagger {

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("描述:简单优雅的restfun风格")
                .termsOfServiceUrl("http://www.lyon.com")
                //.contact(new Contact("kebi", "tt", "[email protected]"))//作者
                .version("1.0")
                .build();
    }

    @SuppressWarnings("unchecked")
       @Bean
       public Docket commonApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                   .groupName("common")
                   .genericModelSubstitutes(DeferredResult.class)
//                   .genericModelSubstitutes(ResponseEntity.class)
                   .useDefaultResponseMessages(false)
                   .forCodeGeneration(true)
                   .pathMapping("/")// base,最终调用接口后会和paths拼接在一起
                   .select()
                   .paths(or(regex("/common/.*")))//过滤的接口
                   .build()
                   .apiInfo(commonApiInfo());
    }

    private ApiInfo commonApiInfo() {
        return new ApiInfoBuilder()
                .title("common页面API")//大标题
                .description("springboot平台的REST API")//详细描述
                .version("1.0")//版本
                .contact(new Contact("lyon", "", ""))//作者
                .build();
    }

配置了分组

默认

@Bean
public Docket createRestApi()

添加了分组

@Bean
public Docket commonApi()

分组注意过滤接口地址

.paths(or(regex("/common/.*")))   //过滤的接口

三、Controller

/**
     * 根据ID查询用户
     * @param id
     * @return
     */
    @ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
    @ApiImplicitParam(name = "id", value = "用户ID", dataType = "Integer", paramType = "path")
    @RequestMapping(value = "user/{id}", method = RequestMethod.GET)
    @ResponseBody
    public User getUserById (@PathVariable(value = "id") Integer id){
        System.out.println("id = " + id);

        User user = null;
        if(id == 1){
            user = new User(1, "科比");
        } else {
            user = new User(id, "我是科比粉丝");
        }
        return user;
    }

测试结果

分组common

@Controller
@RequestMapping("common")
public class CommonController {

    @ApiOperation(value="获取部门详细信息", notes="根据url的id来获取部门详细信息")
    //@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
    @RequestMapping(value = "dept/{id}", method = RequestMethod.GET)
    @ResponseBody
    public Dept getDeptById (@PathVariable(value = "id") Integer id){
        System.out.println("id = " + id);

        Dept dept = null;
        if(id == 1){
            dept = new Dept(1, "综合部");
        } else {
            dept = new Dept(id, "其他部门");
        }
        return dept;
    }

四、汉化操作

上面之所以显示中文是实现了汉化

1.在resourece目录下创建\META-INF\resoures目录,然后创建一个名称为"swagger-ui.html" 的HTML文件。

2.html内容

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-32x32.png" sizes="32x32"/>
    <link rel="icon" type="image/png" href="webjars/springfox-swagger-ui/images/favicon-16x16.png" sizes="16x16"/>
    <link href=‘webjars/springfox-swagger-ui/css/typography.css‘ media=‘screen‘ rel=‘stylesheet‘ type=‘text/css‘/>
    <link href=‘webjars/springfox-swagger-ui/css/reset.css‘ media=‘screen‘ rel=‘stylesheet‘ type=‘text/css‘/>
    <link href=‘webjars/springfox-swagger-ui/css/screen.css‘ media=‘screen‘ rel=‘stylesheet‘ type=‘text/css‘/>
    <link href=‘webjars/springfox-swagger-ui/css/reset.css‘ media=‘print‘ rel=‘stylesheet‘ type=‘text/css‘/>
    <link href=‘webjars/springfox-swagger-ui/css/print.css‘ media=‘print‘ rel=‘stylesheet‘ type=‘text/css‘/>

    <script src=‘webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/lib/jquery.slideto.min.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/lib/lodash.min.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/lib/backbone-min.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/swagger-ui.min.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/lib/jsoneditor.min.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/lib/marked.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/lib/swagger-oauth.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/springfox.js‘ type=‘text/javascript‘></script>

    <!--国际化操作:选择中文版 -->
    <script src=‘webjars/springfox-swagger-ui/lang/translator.js‘ type=‘text/javascript‘></script>
    <script src=‘webjars/springfox-swagger-ui/lang/zh-cn.js‘ type=‘text/javascript‘></script>

</head>

<body class="swagger-section">
<div id=‘header‘>
    <div class="swagger-ui-wrap">
        <a id="logo" href="http://swagger.io"><span class="logo__title">swagger</span></a>
        <form id=‘api_selector‘>
            <div class=‘input‘>
                <select id="select_baseUrl" name="select_baseUrl"></select>
            </div>
            <div class=‘input‘><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>
            <div id=‘auth_container‘></div>
            <div class=‘input‘><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div>
        </form>
    </div>
</div>

<div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</body>
</html>

参考了:

汉化:https://www.jianshu.com/p/7e543f0f0bd8

分组:http://blog.csdn.net/stonexmx/article/details/77604571

原文地址:https://www.cnblogs.com/lyon91/p/8446505.html

时间: 2024-10-23 00:20:00

springboot利用swagger构建api文档的相关文章

SpringBoot使用Swagger2构建API文档

1.Swagger2介绍 Swagger2这套自动化文档工具来生成文档,它可以轻松的整合到Spring Boot中,并与Spring MVC程序配合组织出强大RESTful API文档. 2.SpringBoot开启Swagger2支持 1.导入依赖 <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <versio

白话SpringCloud | 第十一章:路由网关(Zuul):利用swagger2聚合API文档

前言 通过之前的两篇文章,可以简单的搭建一个路由网关了.而我们知道,现在都奉行前后端分离开发,前后端开发的沟通成本就增加了,所以一般上我们都是通过swagger进行api文档生成的.现在由于使用了统一路由网关了,都希望各微服务的api文档统一的聚合在网关服务中,也方便前端用户查阅,不需要每个服务单独查看.当然了,也是可以做一个文档索引网页进行各微服务的api文档链接的.今天,我们就来讲下使用swagger实现自动化聚合微服务文档功能. 注:关于Swagger的介绍和使用,由于在之前的Spring

Spring Boot中使用Swagger2构建API文档

程序员都很希望别人能写技术文档,自己却很不愿意写文档.因为接口数量繁多,并且充满业务细节,写文档需要花大量的时间去处理格式排版,代码修改后还需要同步修改文档,经常因为项目时间紧等原因导致文档滞后于代码,接口调用方的抱怨声不绝于耳.而程序员是最擅长"偷懒"的职业了,自然会有多种多样的自动生成文档的插件.今天要介绍的就是Swagger. 接下来我们在Spring Boot中使用Swagger2构建API文档 Swagger是一个简单但功能强大的API表达工具.它具有地球上最大的API工具生

Core Web API上使用Swagger提供API文档

在ASP.NET Core Web API上使用Swagger提供API文档 我在开发自己的博客系统(http://daxnet.me)时,给自己的RESTful服务增加了基于Swagger的API文档功能.当设置IISExpress的默认启动路由到Swagger的API文档页面后,在IISExpress启动Web API站点后,会自动重定向到API文档页面,非常方便.这不仅让我能够快速省查API设计的合理性,同时从API的使用角度也为我自己提供了便捷.下图就是我的博客系统RESTful API

浅析如何在Nancy中使用Swagger生成API文档

原文:浅析如何在Nancy中使用Swagger生成API文档 前言 上一篇博客介绍了使用Nancy框架内部的方法来创建了一个简单到不能再简单的Document.但是还有许许多多的不足. 为了能稍微完善一下这个Document,这篇引用了当前流行的Swagger,以及另一个开源的Nancy.Swagger项目来完成今天的任务! 注:Swagger是已经相对成熟的了,但Nancy(2.0.0-clinteastwood)和Nancy.Swagger(2.2.6-alpha)是基于目前的最新版本,但目

Asp.Net Core下使用swagger生成api文档

目录 一.前期准备 二.配置Swagger 三.参考 .Net Core中有两个集成NSwag的包,分别为Swashbuckle和NSwag.两者的配置大同小异.这里以NSwag为例. 一.前期准备 1.初始化asp.net core 测试项目 新建asp.net core项目,此处略过: 新建apicontroller,并编写测试代码: [Route("api/[controller]")] [ApiController] public class UserApiController

Laravel(PHP)使用Swagger生成API文档不完全指南 - 基本概念和环境搭建 - 简书

在PHPer中,很多人听说过Swagger,部分人知道Swagger是用来做API文档的,然而只有少数人真正知道怎么正确使用Swagger,因为PHP界和Swagger相关的资料实在是太少了.所以鄙人斗胆一试,希望能以本文帮助到大家了解Swagger,从此告别成天用Word.Markdown折腾API文档的日子. 什么是Swagger Swagger is a simple yet powerful representation of your RESTful API. With the lar

Spring MVC中使用Swagger生成API文档和完整项目示例Demo,swagger-server-api

本文作者:小雷FansUnion-一个有创业和投资经验的资深程序员-全球最大中文IT社区CSDN知名博主-排名第119 实际项目中非常需要写文档,提高Java服务端和Web前端以及移动端的对接效率. 听说Swagger这个工具,还不错,就网上找了些资料,自己实践了下. 一:Swagger介绍 Swagger是当前最好用的Restful API文档生成的开源项目,通过swagger-spring项目 实现了与SpingMVC框架的无缝集成功能,方便生成spring restful风格的接口文档,

ASP.NET Core 3.0 WebApi中使用Swagger生成API文档简介

参考地址,官网:https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-2.2&tabs=visual-studio 与https://www.jianshu.com/p/349e130e40d5 当一个WebApi完成之后,书写API文档是一件非常头疼的事,因为不仅要写得清楚,能让调用接口的人看懂,又是非常耗时耗力的一件事.在之前的一篇随笔中(