YouTipSwagger UI and Documentation Publishing
\n\nSwagger UI is an API documentation visualization tool based on the OpenAPI specification (formerly the Swagger specification). It converts API specification documents into interactive API documentation interfaces.
\n\nThrough Swagger UI, developers and users can:
\n\n- \n
- View detailed API information \n
- Test API requests directly on the interface \n
- View request and response examples \n
- Understand the functionality and parameters of different API endpoints \n
Advantages of Swagger UI
\n\n- \n
- Visualization: Provides a clear and intuitive API documentation interface \n
- Interactivity: Supports online API testing without additional tools \n
- Real-time updates: Documentation automatically updates when code changes \n
- Standardization: Based on the OpenAPI specification for consistency \n
- Cross-language support: Compatible with various programming languages and frameworks \n
\n\n
Integrating Swagger UI
\n\n1. Integration in Spring Boot Projects
\n\nAdd Dependencies
\n\nAdd the following dependencies to pom.xml:
Example
\n\n\nio.springfox\n\nspringfox-swagger2\n\n3.0.0\n\n\n\nio.springfox\n\nspringfox-swagger-ui\n\n3.0.0\n\nOr use SpringDoc OpenAPI:
\n\nExample
\n\norg.springdoc\n\nspringdoc-openapi-ui\n\n1.6.14\n\nConfigure Swagger
\n\nExample
\nimport org.springframework.context.annotation.Bean;\n\nimport org.springframework.context.annotation.Configuration;\n\nimport springfox.documentation.builders.ApiInfoBuilder;\n\nimport springfox.documentation.builders.PathSelectors;\n\nimport springfox.documentation.builders.RequestHandlerSelectors;\n\nimport springfox.documentation.service.ApiInfo;\n\nimport springfox.documentation.service.Contact;\n\nimport springfox.documentation.spi.DocumentationType;\n\nimport springfox.documentation.spring.web.plugins.Docket;\n\nimport springfox.documentation.swagger2.annotations.EnableSwagger2;\n\n@Configuration\n\n @EnableSwagger2\n\npublic class SwaggerConfig {\n\n @Bean\n\npublic Docket api(){\n\nreturn new Docket(DocumentationType.SWAGGER_2)\n\n .select()\n\n .apis(RequestHandlerSelectors.basePackage("com.example.controller"))\n\n .paths(PathSelectors.any())\n\n .build()\n\n .apiInfo(apiInfo());\n\n}\n\nprivate ApiInfo apiInfo(){\n\nreturn new ApiInfoBuilder()\n\n .title("API API Documentation")\n\n .description("API Detailed API Description")\n\n .version("1.0.0")\n\n .contact(new Contact("Development Team", "https://example.com", "team@example.com"))\n\n .build();\n\n}\n\n}\n\nFor SpringDoc OpenAPI:
\n\nExample
\nimport org.springdoc.core.GroupedOpenApi;\n\nimport org.springframework.context.annotation.Bean;\n\nimport org.springframework.context.annotation.Configuration;\n\nimport io.swagger.v3.oas.models.OpenAPI;\n\nimport io.swagger.v3.oas.models.info.Info;\n\nimport io.swagger.v3.oas.models.info.Contact;\n\n@Configuration\n\npublic class SwaggerConfig {\n\n @Bean\n\npublic OpenAPI customOpenAPI(){\n\nreturn new OpenAPI()\n\n .info(new Info()\n\n .title("API API Documentation")\n\n .version("1.0.0")\n\n .description("API Detailed API Description")\n\n .contact(new Contact()\n\n .name("Development Team")\n\n .email("team@example.com")\n\n .url("https://example.com")));\n\n}\n\n@Bean\n\npublic GroupedOpenApi publicApi(){\n\nreturn GroupedOpenApi.builder()\n\n .group("public-apis")\n\n .pathsToMatch("/api/**")\n\n .build();\n\n}\n\n}\n\n2. Integration in Node.js Express Projects
\n\nInstall Dependencies
\nnpm install swagger-jsdoc swagger-ui-express --save\nConfigure Swagger
\n\nExample
\nconst express = require('express');\n\nconst swaggerJsDoc = require('swagger-jsdoc');\n\nconst swaggerUi = require('swagger-ui-express');\n\nconst app = express();\n\n// Swagger Configuration\n\nconst swaggerOptions ={\n\n definition:{\n\n openapi:'3.0.0',\n\n info:{\n\n title:'API API Documentation',\n\n version:'1.0.0',\n\n description:'API Detailed API Description',\n\n contact:{\n\n name:'Development Team',\n\n email:'team@example.com',\n\n url:'https://example.com'\n\n}\n\n},\n\n servers:[\n\n{\n\n url:'http://localhost:3000',\n\n description:'Development Server'\n\n}\n\n]\n\n},\n\n apis:['./routes/*.js']// API Path to Route File\n\n};\n\nconst swaggerDocs = swaggerJsDoc(swaggerOptions);\n\n app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));\n\n// ... Other Routes and Middleware\n\napp.listen(3000,()=>{\n\n console.log('Server runs at http://localhost:3000');\n\n console.log('API Documentation available at http://localhost:3000/api-docs Access');\n\n});\n\n3. Using in Python FastAPI Projects
\n\nFastAPI integrates Swagger UI by default:
\n\nExample
\nfrom fastapi import FastAPI\n\napp = FastAPI(\n\n title="API API Documentation",\n\n description="API Detailed API Description",\n\n version="1.0.0",\n\n contact={\n\n"name": "Development Team",\n\n"email": "team@example.com",\n\n"url": "https://example.com",\n\n},\n\n)\n\n@app.get("/")\n\n async def root():\n\nreturn{"message": "Hello World"}\n\nSwagger UI is accessible by default at the /docs path. You can view the documentation by visiting http://localhost:8000/docs.
For more details, see: FastAPI Interactive API Documentation
\n\n\n\n
Writing API Documentation
\n\n1. API Documentation Annotations in Spring Boot Projects
\n\nExample
\nimport io.swagger.annotations.*;\n\nimport org.springframework.web.bind.annotation.*;\n\n@RestController\n\n @RequestMapping("/api/users")\n\n @Api(tags ="User Management")\n\npublic class UserController {\n\n@ApiOperation(value ="Get User List", notes ="Paginated Get All User Information")\n\n @ApiResponses({\n\n @ApiResponse(code =200, message ="Success"),\n\n @ApiResponse(code =400, message ="Request Parameter Error"),\n\n @ApiResponse(code =500, message ="Server Internal Error")\n\n})\n\n @GetMapping("/")\n\npublic Page getUsers(\n\n @ApiParam(value ="Page Number", required =true) @RequestParam int page,\n\n @ApiParam(value ="Records per Page", required =true) @RequestParam int size){\n\n// Business Logic\n\nreturn userService.getUsers(page, size);\n\n}\n\n@ApiOperation(value ="Get Single User", notes ="Get User Information by ID")\n\n @GetMapping("/{id}")\n\npublic User getUser(\n\n @ApiParam(value ="User ID", required =true) @PathVariable Long id){\n\n// Business Logic\n\nreturn userService.getUser(id);\n\n}\n\n@ApiOperation(value ="Create User", notes ="Create New User")\n\n @PostMapping("/")\n\npublic User createUser(\n\n @ApiParam(value ="User Information", required =true) @RequestBody UserDTO userDTO){\n\n// Business Logic\n\nreturn userService.createUser(userDTO);\n\n}\n\n}\n\nFor SpringDoc OpenAPI:
\n\n