码云 Gitee IDE 全新上线——支持 Git 管理的轻量在线编码环境
Watch Star Fork

Remenber_Ray / Swagger2-RESTfulHTML

加入码云
与超过 300 万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
SpringBoot实现Swagger2
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README.md 4.09 KB

Swagger2-RESTful

官网

1. 认识Swagger

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

2. 添加依赖

       <!-- 添加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> 

3. 启动Swagger2

@Configuration //标记配置类
@EnableSwagger2 //开启在线接口文档
public class Swagger2 {

}

4. 配置控制器

 @RestController
 @RequestMapping(value = "/users") // 通过这里配置使下面的映射都在/users下,可去
 public class UserController {
 
 }

5. 访问Swagger-ui

这是去往 Swagger-ui 的链接。

Swagger-ui


使用Swagger2Markup实现API文档的静态部署

1. 认识Swagger2Markup

Swagger2Markup是Github上的一个开源项目。该项目主要用来将Swagger自动生成的文档转换成几种流行的格式以便于静态部署和使用,比如:AsciiDoc、Markdown、Confluence。 这是去往 Swagger2Markup 的链接。

2. 添加依赖

        <!-- 添加Swagger2markup依赖 -->
       <dependency>
           <groupId>io.github.swagger2markup</groupId>
           <artifactId>swagger2markup</artifactId>
           <version>1.3.1</version>
       </dependency>

3. 单元测试类

/**
* 编写一个单元测试用例来生成执行生成文档的代码
*/
@RunWith(SpringRunner.class)
@SpringBootTest
public class Chapter315ApplicationTests {
}

4. 生成HTML

修改pom.xml

    <build>
       <plugins>
           <plugin>
               <groupId>org.springframework.boot</groupId>
               <artifactId>spring-boot-maven-plugin</artifactId>
           </plugin>
           <!-- 生成Asciidoc -->
           <plugin>
               <groupId>io.github.swagger2markup</groupId>
               <artifactId>swagger2markup-maven-plugin</artifactId>
               <version>1.3.1</version>
               <configuration>
                   <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
                   <outputDir>src/docs/asciidoc/generated</outputDir>
                   <config>
                       <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
                   </config>
               </configuration>
           </plugin>
           <!-- 生成HTML -->
           <plugin>
               <groupId>org.asciidoctor</groupId>
               <artifactId>asciidoctor-maven-plugin</artifactId>
               <version>1.5.6</version>
               <configuration>
                   <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
                   <outputDirectory>src/docs/asciidoc/html</outputDirectory>
                   <backend>html</backend>
                   <sourceHighlighter>coderay</sourceHighlighter>
                   <attributes>
                       <toc>left</toc>
                   </attributes>
               </configuration>
           </plugin>
       </plugins>
   </build>

执行Maven插件

    asciidoctor:process-asciidoc

Maven

HTML


本文结束
这是 本人博客 的链接。

项目点评 ( 0 )

你可以在登录后,发表评论

搜索帮助