[springboot 开发单体web shop] 4. Swagger生成Javadoc

时间 2019-11-09

标签 springboot 开发单体 web shop swagger 生成 javadoc 栏目 Spring 繁體版

原文原文链接

Swagger生成JavaDoc

在平常的工做中，特别是如今先后端分离模式之下，接口的提供形成了咱们先后端开发人员的沟通成本大量提高，由于沟通不到位，不及时而形成的[撕币]事件都成了平常工做。特别是不少的开发人员不擅长沟通，形成的结果就会让本身特别的痛苦，也让合做人员恨的牙根痒痒。为告终束战火蔓延，同时为了提高开发人员的满意度，Swagger应运而生。html

什么是Swagger

> Swagger for Everyone
> Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset.
> Swagger open source and pro tools have helped millions of API developers, teams, and organizations deliver great APIs.java

简言之就是指使用工具集简化用户、团队和企业的API开发。git

集成Swagger

系统中我选择使用的是swagger-spring-boot-starter。 > 该项目主要利用Spring Boot的自动化配置特性来实现快速的将swagger2引入spring boot应用来生成API文档，简化原生使用swagger2的整合代码。看得出来，我在教你们使用的都是在偷懒哦，这可不是什么好现象。。。程序员

添加依赖

<!--整合Swagger2-->
        <dependency>
            <groupid>com.spring4all</groupid>
            <artifactid>swagger-spring-boot-starter</artifactid>
            <version>1.9.0.RELEASE</version>
        </dependency>

点击版本号进入swagger-spring-boot-starter/1.9.0.RELEASE/swagger-spring-boot-starter-1.9.0.RELEASE.pom，能够看到它依赖的版本信息。github

<properties>
        <project.build.sourceencoding>UTF-8</project.build.sourceencoding>
        <version.java>1.8</version.java>
        <version.swagger>2.9.2</version.swagger>
        <version.spring-boot>1.5.10.RELEASE</version.spring-boot>
        <version.lombok>1.18.6</version.lombok>
    </properties>

启用功能

在咱们的启动类ApiApplication上增长@EnableSwagger2Doc注解spring

@SpringBootApplication
@MapperScan(basePackages = "com.liferunner.mapper")
@ComponentScan(basePackages = {"com.liferunner", "org.n3r.idworker"})
@EnableSwagger2Doc //启动Swagger
public class ApiApplication {

    public static void main(String[] args) {
        new SpringApplicationBuilder()
                .sources(ApiApplication.class)
                .run(args);
    }

    @Autowired
    private CORSConfig corsConfig;

    /**
     * 注册跨域配置信息
     *
     * @return {@link CorsFilter}
     */
    @Bean
    public CorsFilter corsFilter() {
        val corsConfiguration = new CorsConfiguration();
        corsConfiguration.addAllowedOrigin(this.corsConfig.getAllowOrigin());
        corsConfiguration.addAllowedMethod(this.corsConfig.getAllowedMethod());
        corsConfiguration.addAllowedHeader(this.corsConfig.getAllowedHeader());
        corsConfiguration.setAllowCredentials(this.corsConfig.getAllowCredentials());

        val urlBasedCorsConfigurationSource = new UrlBasedCorsConfigurationSource();
        urlBasedCorsConfigurationSource.registerCorsConfiguration("/**", corsConfiguration);

        return new CorsFilter(urlBasedCorsConfigurationSource);
    }
}

配置基础信息

能够经过properties文件和yml/yaml文件配置。shell

# 配置swagger2
swagger:
  enabled: true #是否启用swagger，默认：true
  title: 实战电商api平台
  description: provide 电商 API
  version: 1.0.0.RC
  license: Apache License, Version 2.0
  license-url: https://www.apache.org/licenses/LICENSE-2.0.html
  terms-of-service-url: http://www.life-runner.com
  contact:
    email: magicianisaac@gmail.com
    name: Isaac-Zhang
    url: http://www.life-runner.com
  base-package: com.liferunner
  base-path: /**

阶段效果一

运行咱们的api项目，在浏览器输入：http://localhost:8088/swagger-ui.html,能够看到以下：能够看到，咱们在yml文件中配置的信息，展现在了页面的顶部，点击用户管理: 从上图能够看出，咱们的/users/create接口展出出来，而且要传入的参数，请求类型等等信息都已经展现在上图中。可是，要传递的参数是什么意思，都是咱们的字段信息，咱们要如何让它更友好的展现给调用方呢？让咱们继续完善咱们的文档信息：apache

完善说明信息

在咱们建立用户的时候，须要传递一个com.liferunner.dto.UserRequestDTO对象，这个对象的属性以下：bootstrap

@RestController
@RequestMapping(value = "/users")
@Slf4j
@Api(tags = "用户管理")
public class UserController {

    @Autowired
    private IUserService userService;

    @ApiOperation(value = "用户详情", notes = "查询用户")
    @ApiIgnore
    @GetMapping("/get/{id}")
    //@GetMapping("/{id}") 若是这里设置位这样，每次请求swagger都会进到这里，是一个bug
    public String getUser(@PathVariable Integer id) {
        return "hello, life.";
    }

    @ApiOperation(value = "建立用户", notes = "用户注册接口")
    @PostMapping("/create")
    public JsonResponse createUser(@RequestBody UserRequestDTO userRequestDTO) {
        //...
    }
}

@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
@ApiModel(value = "建立用户DTO", description = "用户注册须要的参数对象")
public class UserRequestDTO {
    @ApiModelProperty(value = "用户名", notes = "username", example = "isaaczhang", required = true)
    private String username;
    @ApiModelProperty(value = "注册密码", notes = "password", example = "12345678", required = true)
    private String password;
    @ApiModelProperty(value = "确认密码", notes = "confimPassword", example = "12345678", required = true)
    private String confirmPassword;
}

能够看到，咱们有不少经过@Apixxx开头的注解说明，这个就是Swagger提供给咱们用以说明字段和文档说明的注解。segmentfault

@Api 表示对外提供API
@ApiIgnore 表示不对外展现，可用于类和方法
@ApiOperation 就是指的某一个API下面的CURD动做
@ApiResponses 描述操做可能出现的异常状况
@ApiParam 描述传递的单参数信息
@ApiModel 用来描述java object的属性说明
@ApiModelProperty 描述object 字段说明全部的使用，均可以进入到相关的注解的具体class去查看全部的属性信息，都比较简单，这里就不作具体描述了。想要查看更多的属性说明，你们能够进入：Swagger属性说明传送门。

配置完以后，重启应用，刷新UI页面：上图中红框圈定的都是咱们从新配置的说明信息，足够简单明了吧～

集成更好用的UI界面

针对于API说明来讲，咱们上述的信息已经足够优秀了，但是作技术，咱们应该追求的是更加极致的地步，上述的UI界面在咱们提供大批量用户接口的时候，友好型就有那么一丢丢的欠缺了，如今给你们再介绍一款更好用的开源Swagger UI，有请swagger-bootstrap-ui。咱们从上图能够看到，这个UI的Star数目已经超过1.1K了，这就证实它已经很优秀了，咱们接下来解开它的庐山真面目吧。

集成依赖

只须要在咱们的expensive-shop\pom.xml中加入如下依赖代码：

<!--一种新的swagger ui-->
        <dependency>
            <groupid>com.github.xiaoymin</groupid>
            <artifactid>swagger-bootstrap-ui</artifactid>
            <version>1.6</version>
        </dependency>

预览效果

添加完依赖后，只须要重启咱们的应用，而后访问http://localhost:8088/doc.html,效果以下：点击建立用户：上述的效果是否是更符合咱们的审美了～到此为止，咱们使用Swagger来动态生成API的效果已经所有演示完了，可是若是某一天咱们要和一个不能链接查看咱们网站的客户进行集成的时候，咱们怎么办呢？仍是要手写一份文档给他们吗？那咱们不就同样很痛苦吗！！！做为程序员，咱们是绝对不能容许这种状况发生的！那就让咱们继续看下去。

生成离线文档

为了避免让咱们作痛苦的工做，咱们既然已经在代码中添加了那么多的说明信息，是否有一种方式能够帮助咱们来生成一份离线的文档呢？答案是确定的。

开源项目swagger2markup

> A Swagger to AsciiDoc or Markdown converter to simplify the generation of an up-to-date RESTful API documentation by combining documentation that’s been hand-written with auto-generated API documentation.

源码传送门
 documents传送门 > Swagger2Markup它主要是用来将Swagger自动生成的文档转换成几种流行的格式以便离线使用
> 格式：AsciiDoc、HTML、Markdown、Confluence

使用MAVEN插件生成AsciiDoc文档

在mscx-shop-api\pom.xml中加入如下依赖代码：

<build>
        <plugins>
            <!--生成 AsciiDoc 文档(swagger2markup)-->
            <plugin>
                <groupid>io.github.swagger2markup</groupid>
                <artifactid>swagger2markup-maven-plugin</artifactid>
                <version>1.3.3</version>
                <configuration>
                    <!--这里是要启动咱们的项目，而后抓取api-docs的返回结果-->
                    <swaggerinput>http://localhost:8088/v2/api-docs</swaggerinput>
                    <outputdir>src/docs/asciidoc/generated-doc</outputdir>
                    <config>
                        <swagger2markup.markuplanguage>ASCIIDOC</swagger2markup.markuplanguage>
                    </config>
                </configuration>
            </plugin>
        </plugins>
    </build>

<swaggerinput>http://localhost:8088/v2/api-docs</swaggerinput> 是为了获取咱们的api JSON数据，以下图：
<outputdir>src/docs/asciidoc/generated-doc</outputdir> 设置咱们要生成的目录地址

执行命令:

expensive-shop\mscx-shop-api&gt;mvn swagger2markup:convertSwagger2markup

要是你们以为命令太长了，也能够点击IDEA => Maven => mscx-shop-api => Plugins => swagger2markup => swagger2markup:convertSwagger2markup 就能够执行啦，以下图：生成结果以下： adoc文件生成好了，那么咱们使用它来生成html吧

使用MAVEN插件生成HTML

在mscx-shop-api\pom.xml中加入如下依赖代码：

<!--生成 HTML 文档-->
            <plugin>
                <groupid>org.asciidoctor</groupid>
                <artifactid>asciidoctor-maven-plugin</artifactid>
                <version>1.5.6</version>
                <configuration>
                    <sourcedirectory>src/docs/asciidoc/generated-doc</sourcedirectory>
                    <outputdirectory>src/docs/asciidoc/html</outputdirectory>
                    <backend>html</backend>
                    <sourcehighlighter>coderay</sourcehighlighter>
                    <attributes>
                        <toc>left</toc>
                    </attributes>
                </configuration>
            </plugin>

<sourcedirectory>src/docs/asciidoc/generated-doc</sourcedirectory> 源文件目录指定为咱们上一节生成的adoc
<outputdirectory>src/docs/asciidoc/html</outputdirectory> 指定输出目录

执行生成命令：

\expensive-shop\mscx-shop-api&gt;mvn asciidoctor:process-asciidoc

生成结果以下：打开overview.html,以下：

至此，咱们的文档就已经所有生成了！

下节预告

下一节咱们将继续开发咱们的用户登陆以及首页信息的部分展现，在过程当中使用到的任何开发组件，我都会经过专门的一节来进行介绍的，兄弟们末慌！

gogogo！

奔跑的人生 | 博客园 | segmentfault | spring4all | csdn | 掘金 | OSChina | 简书 | 头条 | 知乎 | 51CTO